Skip to content

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):

FieldTypeRequiredDescription
codestringyes
detailstringyes
lengthintegernoSearch query errors: length in characters of the offending part of q.
parameterstringnoThe offending parameter, for 400 responses.
positionintegernoSearch query errors: character offset in q.
request_idstringyes
statusintegeryes
titlestringyes
typestring (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.

JSON
{
  "type": "…",
  "title": "…",
  "status": 400,
  "detail": "…",
  "code": "unknown_parameter",
  "parameter": "fromdate",
  "request_id": "…"
}

Codes

CodeStatusMeaning
invalid_parameter400A parameter has a value the API cannot accept. parameter names it.
unknown_parameter400The request has a query parameter the route does not define. parameter names it.
unauthorized401The API key is missing, unknown or not active.
invalid_token401The bearer token is not valid: expired, revoked, badly signed, or issued for another resource.
forbidden403The token's scope does not cover this route.
not_found404The route or the thing asked for does not exist.
gone410No route answers it.
method_not_allowed405The route does not take this method. The routes that read take GET, HEAD and OPTIONS; the webhook routes name theirs in the reference.
rate_limited429The organization's request rate is exceeded. Wait for Retry-After, then send the request again (see Rate limits and quotas).
timeout504The request exceeded its time limit. Narrow the query (a smaller window, a cik) and try again.
internal500An error inside the API. Retrying may help; if it persists, send the request_id to support.
db_unavailable503The database is temporarily unavailable. Retry after the Retry-After delay.
range_not_satisfiable416The Range header asks for bytes the document does not have.
request_too_large413 or 431The request body or its headers are too large.
warming_up503The answer is computed in the background, and the first computation since the API started has not finished. Retry after the Retry-After delay.
invalid_query400The search query q cannot be read. position and length point at the part of q.
query_too_complex400The search query has too many terms or operators. position and length point at the part of q.
prefix_too_broad400A prefix term (word*) matches too many words. position and length point at it.
negative_only_query400The search query only excludes terms; it needs at least one term to match.
unsupported_operator400The search query uses an operator the search does not support. position and length point at it.
invalid_cursor400The search cursor is not valid for this query.
search_timeout503The search query ran out of time. A narrower query or date range answers faster.
search_busy503Full-text search has a full queue. Repeat the request after Retry-After.
search_unavailable503Full-text search cannot be reached now.
ticker_resolution_unavailable503Tickers cannot be resolved to companies now, so a search by ticker cannot run.
no_text404The filing has no text for the item or section asked for.
not_covered404The filing's form is not covered by this route's dataset. routes names the routes that cover it.
conversion_timeout503Converting the document to text took longer than the request allows. It goes on; repeat the request after Retry-After.
document_too_large422The document is larger than the server converts to text. document links the filed bytes.
unsupported_media_type415A request body that is not application/json.
invalid_body400The request body is not one JSON object, or a change names nothing to change.
callbacks_unavailable503The webhook routes cannot be served by this server just now. Some of these answers carry Retry-After.
plan_required403The organization's plan does not include the filing stream, or webhooks, or this kind of subscription.
limit_reached409The plan's limit is reached; kind says which (endpoints, filter or firehose subscriptions, or manual retries of a delivery), with limit and used.
conflict409The endpoint changed while the request was being checked. Send it again.
quota_exceeded429The 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).
blocked403The organization of the key or token is suspended.
invalid_state409The delivery cannot be retried: it is not failed, it was billed, or it is a test send or a verification.
replay_running409A replay of this endpoint started a short time ago. Wait for Retry-After.
test_running409Another test send of the organization has not answered yet.
endpoint_unverified409The endpoint has not answered its challenge yet; see Webhooks.
endpoint_disabled409The 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 of title or detail.
  • 4xx: fix the request. Retrying the same request gives the same answer. A 400 names the parameter at 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_id is also in the X-Request-Id response 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

  • 206 is the answer to a Range request for part of a document.
  • 304 is the answer when If-None-Match matches the document's ETag: your copy is current.

Markdown version: /docs/errors.md