Errors
Errors are RFC 9457 problem bodies, served as application/problem+json, with the appropriate HTTP status. A problem body always has a stable, machine-readable code and the request_id of the request. The one exception is the 503 of GET /v3/health ; it carries the same health body as a 200.
Errors (problem bodies):
| Field | Type | Required | Description |
|---|---|---|---|
code | string | yes | |
detail | string | yes | |
length | integer | no | Search query errors: length in characters of the offending part of q. |
parameter | string | no | The offending parameter, for 400 responses. |
position | integer | no | Search query errors: character offset in q. |
request_id | string | yes | |
status | integer | yes | |
title | string | yes | |
type | string (URI) | yes |
The shape of a 400 for a misspelled parameter. The dots stand for text the API writes; match on code; title and detail are for people and may change.
{
"type": "…",
"title": "…",
"status": 400,
"detail": "…",
"code": "unknown_parameter",
"parameter": "fromdate",
"request_id": "…"
}Codes
| Code | Status | Meaning |
|---|---|---|
invalid_parameter | 400 | A parameter has a value the API cannot accept. parameter names it. |
unknown_parameter | 400 | The request has a query parameter the route does not define. parameter names it. |
unauthorized | 401 | The API key is missing, unknown or not active. |
invalid_token | 401 | The bearer token is not valid: expired, revoked, badly signed, or issued for another resource. |
forbidden | 403 | The token's scope does not cover this route. |
not_found | 404 | The route or the thing asked for does not exist. |
gone | 410 | No route answers it. |
method_not_allowed | 405 | The route does not take this method. The routes that read take GET, HEAD and OPTIONS; the webhook routes name theirs in the reference. |
rate_limited | 429 | The organization's request rate is exceeded. Wait for Retry-After, then send the request again (see Rate limits and quotas). |
timeout | 504 | The request exceeded its time limit. Narrow the query (a smaller window, a cik) and try again. |
internal | 500 | An error inside the API. Retrying may help; if it persists, send the request_id to support. |
db_unavailable | 503 | The database is temporarily unavailable. Retry after the Retry-After delay. |
range_not_satisfiable | 416 | The Range header asks for bytes the document does not have. |
request_too_large | 413 or 431 | The request body or its headers are too large. |
warming_up | 503 | The answer is computed in the background, and the first computation since the API started has not finished. Retry after the Retry-After delay. |
invalid_query | 400 | The search query q cannot be read. position and length point at the part of q. |
query_too_complex | 400 | The search query has too many terms or operators. position and length point at the part of q. |
prefix_too_broad | 400 | A prefix term (word*) matches too many words. position and length point at it. |
negative_only_query | 400 | The search query only excludes terms; it needs at least one term to match. |
unsupported_operator | 400 | The search query uses an operator the search does not support. position and length point at it. |
invalid_cursor | 400 | The search cursor is not valid for this query. |
search_timeout | 503 | The search query ran out of time. A narrower query or date range answers faster. |
search_busy | 503 | Full-text search has a full queue. Repeat the request after Retry-After. |
search_unavailable | 503 | Full-text search cannot be reached now. |
ticker_resolution_unavailable | 503 | Tickers cannot be resolved to companies now, so a search by ticker cannot run. |
no_text | 404 | The filing has no text for the item or section asked for. |
not_covered | 404 | The filing's form is not covered by this route's dataset. routes names the routes that cover it. |
conversion_timeout | 503 | Converting the document to text took longer than the request allows. It goes on; repeat the request after Retry-After. |
document_too_large | 422 | The document is larger than the server converts to text. document links the filed bytes. |
unsupported_media_type | 415 | A request body that is not application/json. |
invalid_body | 400 | The request body is not one JSON object, or a change names nothing to change. |
callbacks_unavailable | 503 | The webhook routes cannot be served by this server just now. Some of these answers carry Retry-After. |
plan_required | 403 | The organization's plan does not include the filing stream, or webhooks, or this kind of subscription. |
limit_reached | 409 | The plan's limit is reached; kind says which (endpoints, filter or firehose subscriptions, or manual retries of a delivery), with limit and used. |
conflict | 409 | The endpoint changed while the request was being checked. Send it again. |
quota_exceeded | 429 | The month's included data transfer is used up and the organization has no prepaid credit. The body says when the allowance resets (see Rate limits and quotas). |
blocked | 403 | The organization of the key or token is suspended. |
invalid_state | 409 | The delivery cannot be retried: it is not failed, it was billed, or it is a test send or a verification. |
replay_running | 409 | A replay of this endpoint started a short time ago. Wait for Retry-After. |
test_running | 409 | Another test send of the organization has not answered yet. |
endpoint_unverified | 409 | The endpoint has not answered its challenge yet; see Webhooks. |
endpoint_disabled | 409 | The endpoint is inactive or disabled. |
A subscription whose query has q, doctypes, primary_only=true or entityName gets 400 invalid_parameter naming that parameter. The webhook routes are described in Webhooks.
Handling errors
- Branch on
code, not on the wording oftitleordetail. - 4xx: fix the request. Retrying the same request gives the same answer. A 400 names the
parameterat fault. - 503 and 504: retry. A 503 carries
Retry-After; wait that long, then send the same request again. Back off further if it repeats. request_idis also in theX-Request-Idresponse header. Support can find a request by it.- An error that is not a problem body (a plain 429, 502 or 503 page) comes from the proxy in front of the API, not from the API itself: during a restart, or when one address sends requests faster than the proxy allows. Treat it as retryable, with a pause.
Statuses that are not errors
206is the answer to aRangerequest for part of a document.304is the answer whenIf-None-Matchmatches the document'sETag: your copy is current.
Markdown version: /docs/errors.md