Skip to content

This is the staging environment's documentation. It is a draft and may change at any time.

List a notice's earlier versions

GET
/notices/{noticeId}/versions
curl --request GET \
--url 'https://api-staging.fedwright.com/v1/notices/e6a41be9630d4261b6f3131923fdc4ce/versions?limit=50' \
--header 'Authorization: Bearer <token>'

Versions that an in-place change replaced, newest first. The current version is the notice itself.

Data source: SAM.gov contract opportunities.

noticeId
required

SAM.gov NoticeId.

string
/^[0-9a-f]{32}$/

SAM.gov NoticeId.

limit
integer
default: 50 >= 1 <= 200

Maximum number of items to return.

cursor
string
<= 2048 characters

Opaque cursor from a previous response’s nextCursor.

A page of earlier versions.

Media typeapplication/json
object
nextCursor
required

Cursor for the next page, or null on the last page.

null | string
items
required
Array<object>

An earlier version of a notice, replaced by an in-place change.

object
contentHash
required

The SHA-256 digest of the version’s normalized content, as 64 lowercase hexadecimal characters.

string
/^[0-9a-f]{64}$/
extractId
required

The SHA-256 of the extract this version came from.

string
/^[0-9a-f]{64}$/
noticeId
required

SAM.gov NoticeId.

string
/^[0-9a-f]{32}$/
snapshot
required

A SAM.gov notice, normalized. Raw values are kept where normalization loses information.

object
agency
required

The agency fields of a notice, as SAM.gov gives them, with the department also reduced to a matching key.

object
aacCode
required

The activity address code (AAC) that identifies the contracting office. Null when the notice has none.

null | string
cgac
required

The department’s three-digit CGAC (Common Government-wide Accounting Classification) code. Null when the notice has none.

null | string
department
required

The department as SAM.gov names it. Null for the rows with no agency.

null | string
departmentKey
required

The department name uppercased, letters and digits only.

null | string
fpdsCode
required

The FPDS (Federal Procurement Data System) code of the contracting office. Null when the notice has none.

null | string
office
required

The contracting office’s name, as SAM.gov gives it. Null when the notice has none.

null | string
organizationType
required

The type of organization SAM.gov records for the issuing office, such as OFFICE. Null when the notice has none.

null | string
subTier
required

The sub-tier agency’s name, as SAM.gov gives it. Null when the notice has none.

null | string
archive
required

SAM.gov’s archive policy for the notice.

object
date
required

The date SAM.gov archives the notice. Null when SAM.gov gives none.

null | string format: date
type
required

SAM.gov’s archive type for the notice, such as auto15. Null when SAM.gov gives none.

null | string
award
required
One of:

Award fields as the notice carries them. Award notices also produce an Award.

object
amount
required
One of:

A monetary amount in one currency.

object
amount
required

Decimal amount as a string, so no precision is lost.

string
/^-?[0-9]+(\.[0-9]+)?$/
currency
required

ISO 4217 currency code.

string
/^[A-Z]{3}$/
awardeeRaw
required

The awardee’s name as the notice gives it, or null when it gives none.

null | string
date
required

The award date the notice states, or null when it states none.

null | string format: date
number
required

Null when the notice has other award fields but no award number.

null | string
baseType
required

SAM.gov notice type, using its published label.

string
Allowed values: Sources Sought Special Notice Presolicitation Consolidate/(Substantially) Bundle Solicitation Combined Synopsis/Solicitation Sale of Surplus Property Modification/Amendment/Cancel Award Notice Justification Justification and Approval (J&A)
contacts
required

The notice’s points of contact, at most two.

Array<object>
<= 2 items

A point of contact for a notice, as SAM.gov lists it.

object
email
required

The contact’s email address. Null when the notice gives none.

null | string
fax
required

The contact’s fax number. Null when the notice gives none.

null | string
name
required

The contact’s name. Null when the notice gives none.

null | string
phone
required

The contact’s phone number. Null when the notice gives none.

null | string
role
required

Whether the contact is the notice’s primary or its secondary point of contact.

string
Allowed values: primary secondary
title
required

The contact’s job title. Null when the notice gives none.

null | string
contentHash
required

SHA-256 of the normalized notice.

string
/^[0-9a-f]{64}$/
description
required

Plain text, with HTML entities decoded (hadEntities) and whitespace tidied. Text in angle brackets, such as <https://...> or <Company Name>, is kept. SAM.gov cuts descriptions off at about 32,000 characters (truncated).

object
formattedDescription
One of:

A description formatted as Markdown. Only core CommonMark paragraphs, headings, bold field labels, and lists to depth 5 appear, and each list item keeps its source label as an escaped prefix, such as \(1\). Render it with a sanitizing CommonMark renderer that treats links, images, raw HTML, and code as literal text, with one exception (2026-10-27): an ordered list whose source numbered it with letters or Roman numerals (a), (iv)) is preceded by a line holding exactly the comment <!-- fedwright:list style=lower-alpha delimiter=period --> (style: lower-alpha, upper-alpha, lower-roman, upper-roman; delimiter: period, paren, parens), and the list is numbered 1. 2. 3.. A client shows the letters the style names (CSS list-style-type) and never shows the comment as text; one that ignores it still shows a correct numbered list. <!-- fedwright:list style=decimal --> only ends a lettered list directly above a numbered one. Any other comment or HTML is literal text.

object
formatterVersion
required

An opaque identifier of the prompt, script schema, and renderer that formatted it.

string
markdown
required

The description formatted as Markdown.

string
hadEntities
required

The text had HTML entities, such as &#39;, which were decoded.

boolean
length
required

The length of text in characters.

integer
text
required

The notice’s description as plain text.

string
truncated
required

True when SAM.gov cut the description off, so text is incomplete.

boolean
enrichment
required
One of:

The current AI output, separate from SAM.gov fields; evidence quotes include the cited text.

object
amendment
required
One of:
null
conditions
required

Conditions on eligibility that the notice states, such as set-aside restrictions.

Array<object>

A condition on eligibility that the notice states.

object
evidence
required

The quotes from the notice that support the condition.

Array<object>

A quote from the notice that supports an enriched value.

object
quote
required

The quoted text.

string
sourceField
required

The notice field the quote comes from, such as description.

string
id
required

The condition, taken from a fixed list. other means a condition that is not on the list.

string
otherText
required

A short statement of the condition when id is other, otherwise null.

null | string
confidence
required

How confident the enrichment is in each of its sections.

object
amendment
required

How confident the enrichment is in a section: high, medium, or low.

string
Allowed values: high medium low
conditions
required

How confident the enrichment is in a section: high, medium, or low.

string
Allowed values: high medium low
contacts
required

How confident the enrichment is in a section: high, medium, or low.

string
Allowed values: high medium low
contractType
required

How confident the enrichment is in a section: high, medium, or low.

string
Allowed values: high medium low
estimatedValue
required

How confident the enrichment is in a section: high, medium, or low.

string
Allowed values: high medium low
keyDates
required

How confident the enrichment is in a section: high, medium, or low.

string
Allowed values: high medium low
labels
required

How confident the enrichment is in a section: high, medium, or low.

string
Allowed values: high medium low
requirements
required

How confident the enrichment is in a section: high, medium, or low.

string
Allowed values: high medium low
steps
required

How confident the enrichment is in a section: high, medium, or low.

string
Allowed values: high medium low
summary
required

How confident the enrichment is in a section: high, medium, or low.

string
Allowed values: high medium low
contacts
required

Points of contact stated in the notice text.

Array<object>

A point of contact stated in the notice text.

object
email
required

The contact’s email address, or null when the text states none.

null | string
name
required

The contact’s name, or null when the text states none.

null | string
phone
required

The contact’s phone number, or null when the text states none.

null | string
role
required

The contact’s role as the text states it, or null when it states none.

null | string
contractType
required

The contract type as the notice states it, for example firm-fixed-price, or null when it does not state one.

null | string
createdAt
required

When this enrichment was produced.

string format: date-time
enrichmentId
required

The identifier of this enrichment.

string format: uuid
estimatedValue
required
One of:
null
keyDates
required

Dates the notice states, such as when responses or questions are due.

Array<object>

A date the notice states.

object
date
required

The date.

string format: date
evidence
required

The quotes from the notice that support the date.

Array<object>

A quote from the notice that supports an enriched value.

object
quote
required

The quoted text.

string
sourceField
required

The notice field the quote comes from, such as description.

string
kind
required

The role a date plays in responding to the notice: responses_due, questions_due, site_visit, award_expected, or other.

string
Allowed values: responses_due questions_due site_visit award_expected other
time
required

The time of day the text states, or null when it states none.

null | string
timeZone
required

The time zone the text states, or null when it states none.

null | string
labels
required

Topic labels for the notice, taken from a fixed list.

Array<string>
requirements
required

What a responder must have or meet, such as a registration, qualification, or clearance.

Array<object>

A qualification or registration a responder needs.

object
evidence
required

The quotes from the notice that support the requirement.

Array<object>

A quote from the notice that supports an enriched value.

object
quote
required

The quoted text.

string
sourceField
required

The notice field the quote comes from, such as description.

string
kind
required

The category of a requirement: registration, qualification, clearance, or other.

string
Allowed values: registration qualification clearance other
text
required

The requirement in plain language.

string
steps
required

What a responder must do, in the order the notice gives.

Array<object>

A step a responder must take.

object
evidence
required

The quotes from the notice that support the step.

Array<object>

A quote from the notice that supports an enriched value.

object
quote
required

The quoted text.

string
sourceField
required

The notice field the quote comes from, such as description.

string
order
required

The step’s position in the order the notice gives, starting at 1.

integer
>= 1
text
required

The step in plain language.

string
summary
required

A short plain-language summary of the notice.

string
id
required

SAM.gov NoticeId.

string
/^[0-9a-f]{32}$/
links
required

Links to the notice on SAM.gov.

object
public
required

The public SAM.gov page.

string format: uri
sourceWorkspace
required

SAM.gov’s Link, which needs a SAM.gov login.

null | string format: uri
match

The caller organization’s match details.

object
followLevel

How the caller’s organization follows the thread, or null if it does not follow it.

null | string
Allowed values: watching pursuing
grade
required

The score band, from A (best) to D.

string
Allowed values: A B C D
score
required

The match score as a whole number from 0 to 100.

integer
<= 100
state
One of:

A user’s own state for a match.

string
Allowed values: new seen starred dismissed
naics
required
One of:

The NAICS code as given, with every prefix, including the range sectors (31-33, 44-45, 48-49). Filters and matching use matchCodes, which adds the current-edition equivalents of codes from older editions.

object
code
required

The NAICS code as SAM.gov gave it, 2 to 6 digits.

string
/^[0-9]{2,6}$/
currentEquivalents
required

For a code from an older edition, its current-edition codes.

Array<string>
edition
required

The NAICS edition the code comes from. Null when the code isn’t in any edition.

null | string
matchCodes
required

The codes that filters and matching compare against: the code’s prefixes plus the current-edition equivalents of a code from an older edition.

Array<string>
prefixes
required

Every prefix of the code, from the 2-digit sector to the code itself. A sector that spans a range uses the range, such as 31-33.

Array<string>
valid
required

The code exists in the master list, in some edition.

boolean
officeAddress
required

The contracting office’s address, which isn’t the place of performance.

object
city
required

The city, or null when SAM.gov gave none.

null | string
country
required

The country, or null when SAM.gov gave none.

null | string
state
required

The state or territory, or null when SAM.gov gave none.

null | string
zip
required

The postal code, or null when SAM.gov gave none.

null | string
placeOfPerformance
required
One of:

Where the work is to be performed, as the notice gives it.

object
city
required

The city, or null when the notice gives none.

null | string
country
required

ISO 3166-1 alpha-3, as the extract gives it.

null | string
state
required

USPS state or territory code.

null | string
street
required

The street address, or null when the notice gives none.

null | string
zip
required

The postal code, or null when the notice gives none.

null | string
posted
required

SAM.gov’s PostedDate. The extract gives no time zone, and it changes between extracts, so tz is the zone that ingestion detected, or assumed when tzAssumed is true.

object
at
required

The time SAM.gov posted the notice.

string format: date-time
raw
required

The value as SAM.gov gave it.

string
tz
required

The time zone the posted time was read in: UTC or America/New_York (US Eastern).

string
Allowed values: UTC America/New_York
tzAssumed
required

True when SAM.gov gave no time zone and tz is an assumption.

boolean
psc
required
One of:

The product or service code as given, with its hierarchy.

object
code
required

The PSC code, normalized.

string
kind
required

Whether the code is for a product, a service, or rd (research and development), or null when the kind could not be determined.

null | string
Allowed values: product service rd
levels
required

Every level the code identifies, for filters: P:15 is product group 15, S:R4 is service subcategory R4.

Array<string>
raw
required

The code as SAM.gov gave it.

string
retired
required

True when the code has been retired from the PSC list.

boolean
valid
required

The code exists in the PSC master list, including retired codes.

boolean
responseDeadline
required
One of:

at when the deadline has a time; date when SAM.gov gave only a date, which counts as the end of that day in US Eastern time.

object
at
required

The deadline as a point in time, or null when SAM.gov gave a date without a time.

null | string format: date-time
date
required

The deadline’s date, or null when SAM.gov gave a time as well.

null | string format: date
hasTime
required

True when SAM.gov gave a time as well as a date.

boolean
raw
required

The deadline exactly as SAM.gov gave it.

string
tzAssumed
required

True when SAM.gov gave a time without an offset, read as US Eastern.

boolean
setAside
required

state is set for a set-aside code, none_stated when SAM.gov said NONE, and missing when the field was empty.

object
code
required

The SAM.gov set-aside code, or null when none is set.

null | string
label
required

The set-aside’s name, or null when none is set.

null | string
programs
required

The set-aside programs the code belongs to. Empty when none is set.

Array<string>
Allowed values: 8a edwosb hubzone indian_enterprise local_area sdvosb small_business vosb wosb
raw
required

The value as given, for example ["SBA"].

string
soleSource
required

True when the set-aside is a sole-source code.

boolean
state
required

set when the notice has a set-aside code, none_stated when SAM.gov said NONE, and missing when the field was empty.

string
Allowed values: set none_stated missing
solicitationNumber
required
One of:
object
key
required

The solicitation number in uppercase, with letters and digits only. Use it to compare numbers.

string
raw
required

The solicitation number exactly as SAM.gov gave it.

string
sources

Where the notice came from, one entry per upstream record. Absent when source provenance is not yet available.

Array<object>

An upstream record that contributed to a record.

object
firstSeenAt
required

When this publisher first delivered the record.

string format: date-time
formatVersionId
required

The version of the publisher’s format Fedwright read the record with.

null | string
lastSeenAt
required

When this publisher last delivered the record.

string format: date-time
retrievalType
required

A source identifier, such as grantsgov.extract, for the kind of data the record came from.

string
source
required

The publisher, such as grantsgov; derived for a record Fedwright derived.

string
upstreamId
required

The publisher’s own identifier for the record, verbatim.

string
upstreamUrl
required

A link to the record at the publisher, or null when there is none.

null | string format: uri
status
required

firstSeenAt and lastSeenAt are when Fedwright first and last saw the notice in an extract. A notice that leaves the extract is archived, never deleted.

object
active
required

True while the notice is current, meaning it is in SAM.gov’s published data now. False when it is not current, such as a notice from the historical archive or one that is no longer published.

boolean
archivedAt
required

When the notice was archived, or null while it is active.

null | string format: date-time
firstSeenAt
required

When Fedwright first saw the notice.

string format: date-time
lastSeenAt
required

When Fedwright last saw the notice.

string format: date-time
threadId
required

Opaque thread identifier; use the ID the API returns.

string
/^(N:[0-9a-f]{32}|[A-Z0-9]+:[A-Z0-9]+)$/
timeline

The first 50 events in the notice’s thread, oldest first.

Array<object>
<= 50 items

One event in a thread’s history.

object
date
required

When the event happened.

string format: date-time
kind
required

What happened: the thread was created, a notice was amended, corrected (changed in place), awarded, or justified as sole source (sole_source_justified), or the thread was archived.

string
Allowed values: created amended corrected awarded sole_source_justified archived
noticeId
required

SAM.gov NoticeId.

string
/^[0-9a-f]{32}$/
version
required

The version of the notice the event concerns.

integer
>= 1
timelineTruncated

True when the thread has more than 50 events and timeline shows only the first 50.

boolean
title
required

The notice’s title.

string
type
required

SAM.gov notice type, using its published label.

string
Allowed values: Sources Sought Special Notice Presolicitation Consolidate/(Substantially) Bundle Solicitation Combined Synopsis/Solicitation Sale of Surplus Property Modification/Amendment/Cancel Award Notice Justification Justification and Approval (J&A)
version
required

1 when first seen. Each in-place change adds 1.

integer
>= 1
supersededAt
required

When a newer version replaced this one.

string format: date-time
version
required

The version number, starting at 1.

integer
>= 1

Examples

Exampledefault

A page of notice versions

{
"items": [
{
"contentHash": "9aff3b33383676ef817a31d75938d87719d3e898b41cc8b4580f425d2dc21186",
"extractId": "b44d99940d0bf6abacb04a47b2040173bb09c6ad6b936a04dc18ec187aad388c",
"noticeId": "a3fe7c32bd737f251bcfe641ac51f920",
"snapshot": {
"agency": {
"aacCode": "919900",
"cgac": "091",
"department": "EDUCATION, DEPARTMENT OF",
"departmentKey": "EDUCATIONDEPARTMENTOF",
"fpdsCode": "9100",
"office": "CONTRACTS AND ACQUISTIONS MANAGEMEN",
"organizationType": "OFFICE",
"subTier": "EDUCATION, DEPARTMENT OF"
},
"archive": {
"date": "2019-02-01",
"type": "auto15"
},
"award": null,
"baseType": "Special Notice",
"contacts": [
{
"email": "contact61@example.com",
"fax": null,
"name": "Contact Person 62",
"phone": "555-0142",
"role": "primary",
"title": "Contracting Officer"
},
{
"email": "contact62@example.com",
"fax": "555-0206",
"name": "Contact Person 63",
"phone": "555-0143",
"role": "secondary",
"title": "Contracting Officer"
}
],
"contentHash": "9aff3b33383676ef817a31d75938d87719d3e898b41cc8b4580f425d2dc21186",
"description": {
"hadEntities": false,
"length": 240,
"text": "******************************* This notice is amended to include the following additional items: (1) Link for virtual attendees; and (2) Information on one additional planned procurement. Please review the attached, amended special notice.",
"truncated": false
},
"enrichment": null,
"id": "a3fe7c32bd737f251bcfe641ac51f920",
"links": {
"public": "https://sam.gov/opp/a3fe7c32bd737f251bcfe641ac51f920/view",
"sourceWorkspace": "https://sam.gov/workspace/contract/opp/a3fe7c32bd737f251bcfe641ac51f920/view"
},
"naics": {
"code": "541720",
"currentEquivalents": [],
"edition": "2022",
"matchCodes": [
"54",
"541",
"5417",
"54172",
"541720"
],
"prefixes": [
"54",
"541",
"5417",
"54172",
"541720"
],
"valid": true
},
"officeAddress": {
"city": "WASHINGTON",
"country": "USA",
"state": "DC",
"zip": "20202"
},
"placeOfPerformance": {
"city": "WASHINGTON",
"country": "USA",
"state": "DC",
"street": "U.S. Department of Education\nPotomac Center Plaza\n10th Floor Auditorium\n550 12th Street Southwest",
"zip": null
},
"posted": {
"at": "2019-01-09T12:55:08Z",
"raw": "2019-01-09 12:55:08",
"tz": "UTC",
"tzAssumed": true
},
"psc": {
"code": "R",
"kind": "service",
"levels": [
"S",
"S:R"
],
"raw": "R",
"retired": false,
"valid": true
},
"responseDeadline": {
"at": "2019-01-17T15:00:00Z",
"date": null,
"hasTime": true,
"raw": "2019-01-17T10:00:00-05:00",
"tzAssumed": false
},
"setAside": {
"code": null,
"label": null,
"programs": [],
"raw": "",
"soleSource": false,
"state": "missing"
},
"solicitationNumber": {
"key": "91990019R00XX",
"raw": "91990019R00XX"
},
"status": {
"active": true,
"archivedAt": null,
"firstSeenAt": "2026-10-02T03:41:07Z",
"lastSeenAt": "2026-10-02T03:41:07Z"
},
"threadId": "EDUCATIONDEPARTMENTOF:91990019R00XX",
"title": "Notice of Vendor Meeting - NCEE FY19 Procurements",
"type": "Special Notice",
"version": 1
},
"supersededAt": "2026-10-03T03:41:12Z",
"version": 1
}
],
"nextCursor": null
}

The request is malformed, or its schema refuses it: an unknown property, a value of the wrong type or outside its bounds, a limit above 200, or a sort outside the operation’s allow-list (Problem type bad-request). errors names each field by its path, such as nested.note, or $ for the body itself. The request is refused before anything is read or written. A cursor that was altered, has expired, or was issued for other filters, another sort, organization, or user returns Problem type invalid-cursor.

Media typeapplication/problem+json

RFC 9457 Problem Details.

object
detail

An explanation specific to this occurrence of the problem. It is absent for server errors.

string
errors

Validation errors, by field path.

object
key
additional properties
Array<string>
instance

A URI reference that identifies this occurrence of the problem, when the API provides one.

string
limit

On rate-limited, the quota that is used up, such as org-day. On premium-quota-exceeded, org-premium-day. A 429 with an empty body does not name it.

string
resetsAt

On rate-limited from the API and on premium-quota-exceeded, when that quota starts again.

string format: date-time
status
required

The HTTP status code of the response, from 400 to 599.

integer
>= 400 <= 599
title
required

A short, human-readable summary of the problem. Use type to identify the kind of problem, not this text.

string
traceId
required

W3C trace ID of the failed request.

string
type
required

https://fedwright.com/problems/{code}, the same in every environment.

string format: uri

Example generated

{
"detail": "example",
"errors": {
"additionalProperty": [
"example"
]
},
"instance": "example",
"limit": "example",
"resetsAt": "2026-04-15T12:00:00Z",
"status": 1,
"title": "example",
"traceId": "example",
"type": "https://example.com"
}

The access token is missing, expired, or invalid.

Media typeapplication/problem+json

RFC 9457 Problem Details.

object
detail

An explanation specific to this occurrence of the problem. It is absent for server errors.

string
errors

Validation errors, by field path.

object
key
additional properties
Array<string>
instance

A URI reference that identifies this occurrence of the problem, when the API provides one.

string
limit

On rate-limited, the quota that is used up, such as org-day. On premium-quota-exceeded, org-premium-day. A 429 with an empty body does not name it.

string
resetsAt

On rate-limited from the API and on premium-quota-exceeded, when that quota starts again.

string format: date-time
status
required

The HTTP status code of the response, from 400 to 599.

integer
>= 400 <= 599
title
required

A short, human-readable summary of the problem. Use type to identify the kind of problem, not this text.

string
traceId
required

W3C trace ID of the failed request.

string
type
required

https://fedwright.com/problems/{code}, the same in every environment.

string format: uri

Example generated

{
"detail": "example",
"errors": {
"additionalProperty": [
"example"
]
},
"instance": "example",
"limit": "example",
"resetsAt": "2026-04-15T12:00:00Z",
"status": 1,
"title": "example",
"traceId": "example",
"type": "https://example.com"
}

The Problem type says which check refused the caller, when that is about the caller’s own token, client, or role: insufficient-scope when the token’s scopes (or an MCP grant’s) lack the operation’s scope, with WWW-Authenticate: Bearer error="insufficient_scope", scope="..." (RFC 6750) naming the missing scopes; client-not-allowed when the operation doesn’t admit the caller’s kind of client, such as a machine client calling a user-only operation; and insufficient-role when a confirmed member’s roles don’t allow the action. Any other refusal is the generic forbidden, which says nothing more. Another organization’s resource is 404 (not-found) instead, so no reason confirms that it exists. An owner or administrator who sent no proof of a second factor gets mfa-required. An operation that needs an active subscription, when the organization has none, returns subscription-inactive, or organization-suspended when Fedwright suspended the organization. A suspended organization also refuses invitations, new joins through an invitation, and role changes with organization-suspended. Creating or joining an organization without a verified email returns email-unverified, and accepting an invitation sent to another address returns invitation-email-mismatch. A request from Fedwright’s web or mobile app whose session acts for no organization yet returns organization-required, except on getMe, createOrganization, and acceptInvitation. Shared data needs the acting organization’s own subscription; another organization’s doesn’t count.

Media typeapplication/problem+json

RFC 9457 Problem Details.

object
detail

An explanation specific to this occurrence of the problem. It is absent for server errors.

string
errors

Validation errors, by field path.

object
key
additional properties
Array<string>
instance

A URI reference that identifies this occurrence of the problem, when the API provides one.

string
limit

On rate-limited, the quota that is used up, such as org-day. On premium-quota-exceeded, org-premium-day. A 429 with an empty body does not name it.

string
resetsAt

On rate-limited from the API and on premium-quota-exceeded, when that quota starts again.

string format: date-time
status
required

The HTTP status code of the response, from 400 to 599.

integer
>= 400 <= 599
title
required

A short, human-readable summary of the problem. Use type to identify the kind of problem, not this text.

string
traceId
required

W3C trace ID of the failed request.

string
type
required

https://fedwright.com/problems/{code}, the same in every environment.

string format: uri

Example generated

{
"detail": "example",
"errors": {
"additionalProperty": [
"example"
]
},
"instance": "example",
"limit": "example",
"resetsAt": "2026-04-15T12:00:00Z",
"status": 1,
"title": "example",
"traceId": "example",
"type": "https://example.com"
}

The resource does not exist, or belongs to another organization.

Media typeapplication/problem+json

RFC 9457 Problem Details.

object
detail

An explanation specific to this occurrence of the problem. It is absent for server errors.

string
errors

Validation errors, by field path.

object
key
additional properties
Array<string>
instance

A URI reference that identifies this occurrence of the problem, when the API provides one.

string
limit

On rate-limited, the quota that is used up, such as org-day. On premium-quota-exceeded, org-premium-day. A 429 with an empty body does not name it.

string
resetsAt

On rate-limited from the API and on premium-quota-exceeded, when that quota starts again.

string format: date-time
status
required

The HTTP status code of the response, from 400 to 599.

integer
>= 400 <= 599
title
required

A short, human-readable summary of the problem. Use type to identify the kind of problem, not this text.

string
traceId
required

W3C trace ID of the failed request.

string
type
required

https://fedwright.com/problems/{code}, the same in every environment.

string format: uri

Example generated

{
"detail": "example",
"errors": {
"additionalProperty": [
"example"
]
},
"instance": "example",
"limit": "example",
"resetsAt": "2026-04-15T12:00:00Z",
"status": 1,
"title": "example",
"traceId": "example",
"type": "https://example.com"
}

A rate limit is used up. Direct API access counts against the organization’s burst, daily, and monthly quotas, which all its machine clients share; there is no client quota. A 429 comes in two shapes with two header families, so read the response by what it carries.

A machine client’s calls can get a 429 with an empty body. It has three headers: X-RateLimit-Limit, the exhausted rule’s limit and window, such as 3000, 3000;w=2592000; X-RateLimit-Remaining, what is left in that window (0 on a 429); and X-RateLimit-Reset, the seconds until that window resets. It has no Retry-After, no RateLimit headers, no Problem, and does not name the quota. Read the quota from the window w:

w (seconds) Quota
60 Burst.
86400 Daily.
2592000 Monthly (the calendar month is reported as 30 days; X-RateLimit-Reset is exact).

Wait X-RateLimit-Reset seconds before you retry. Refused requests still count: a client that keeps calling after a 429 keeps adding to the counter, so it does not regain budget inside the window. A tier change takes effect within 10 minutes (checkout, the billing portal, and grants alike), once the client gets a new access token.

Every other 429 has a Problem and Retry-After. The Problem type is rate-limited for a used-up quota, or, for an ask, ai-budget-exceeded or premium-quota-exceeded (below). On rate-limited, Retry-After is the seconds until the used-up limit’s window resets, the latest if several are. The Problem also carries limit, the quota that is used up (the one that resets last, if several are), resetsAt, when it starts again, and traceId. RateLimit-Policy and RateLimit describe only the caller’s own limits, here and on every other response a limit applies to. A request refused with rate-limited uses no quota. One refused after that check, for its scope, role, subscription, or kind of client, still counts, so once a quota is used up such a request gets 429 instead of its 403. A request that fails authentication is not counted. An ask that the organization’s AI spending budget can’t cover returns ai-budget-exceeded instead, with Retry-After at the end of the budget’s window: that budget counts what asks cost, not how many there are. An ask that the organization’s premium units for the day can’t cover returns premium-quota-exceeded, with limit (org-premium-day), resetsAt (the next midnight UTC), and Retry-After. That is the plan’s allowance: a plan with no premium units never covers an ask, and a higher plan may. A refused ask uses no units.

Media typeapplication/problem+json

RFC 9457 Problem Details.

object
detail

An explanation specific to this occurrence of the problem. It is absent for server errors.

string
errors

Validation errors, by field path.

object
key
additional properties
Array<string>
instance

A URI reference that identifies this occurrence of the problem, when the API provides one.

string
limit

On rate-limited, the quota that is used up, such as org-day. On premium-quota-exceeded, org-premium-day. A 429 with an empty body does not name it.

string
resetsAt

On rate-limited from the API and on premium-quota-exceeded, when that quota starts again.

string format: date-time
status
required

The HTTP status code of the response, from 400 to 599.

integer
>= 400 <= 599
title
required

A short, human-readable summary of the problem. Use type to identify the kind of problem, not this text.

string
traceId
required

W3C trace ID of the failed request.

string
type
required

https://fedwright.com/problems/{code}, the same in every environment.

string format: uri

Examples

An ask the premium units can't cover

{
"limit": "org-premium-day",
"resetsAt": "2026-11-08T00:00:00Z",
"status": 429,
"title": "Too Many Requests",
"traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
"type": "https://fedwright.com/problems/premium-quota-exceeded"
}
RateLimit
string

For each limit in RateLimit-Policy, the requests r its window still allows and the seconds t until the window resets, such as "org-burst";r=7;t=40, "org-day";r=62;t=41000.

RateLimit-Policy
string

The caller’s rate limits, in the IETF HTTPAPI RateLimit header fields: each limit’s name, its quota q, and its window w in seconds, such as "org-burst";q=20;w=60, "org-day";q=100;w=86400.

Retry-After
integer

Seconds to wait before retrying.

X-RateLimit-Limit
string

On a 429 with an empty body (and on the successful responses that carry these headers), the exhausted rule’s limit and window w in seconds, such as 3000, 3000;w=2592000. The window names the quota: 60 is burst, 86400 is daily, and 2592000 is monthly.

X-RateLimit-Remaining
integer

What is left in that rule’s window (0 on a 429).

X-RateLimit-Reset
integer

Seconds until that rule’s window resets.

Any other error. A request body over 64 KiB returns 413 (payload-too-large), and a request that takes longer than 10 seconds (90 for askOpportunities) returns 503 (request-timeout). An invitation when the API can’t send mail returns 503 (mail-unavailable), and creates nothing. An unexpected failure returns 500 (internal-error) with only type, title, status, and traceId.

Media typeapplication/problem+json

RFC 9457 Problem Details.

object
detail

An explanation specific to this occurrence of the problem. It is absent for server errors.

string
errors

Validation errors, by field path.

object
key
additional properties
Array<string>
instance

A URI reference that identifies this occurrence of the problem, when the API provides one.

string
limit

On rate-limited, the quota that is used up, such as org-day. On premium-quota-exceeded, org-premium-day. A 429 with an empty body does not name it.

string
resetsAt

On rate-limited from the API and on premium-quota-exceeded, when that quota starts again.

string format: date-time
status
required

The HTTP status code of the response, from 400 to 599.

integer
>= 400 <= 599
title
required

A short, human-readable summary of the problem. Use type to identify the kind of problem, not this text.

string
traceId
required

W3C trace ID of the failed request.

string
type
required

https://fedwright.com/problems/{code}, the same in every environment.

string format: uri

Example generated

{
"detail": "example",
"errors": {
"additionalProperty": [
"example"
]
},
"instance": "example",
"limit": "example",
"resetsAt": "2026-04-15T12:00:00Z",
"status": 1,
"title": "example",
"traceId": "example",
"type": "https://example.com"
}