Error codes

There are two kinds of “something is wrong,” and they are handled differently.

A refused value is a successful 200 containing { "unavailable": "..." }. It is a product fact — never an error, never retry it. See below.
A request error is a non-2xx HTTP status. The table is the whole surface.

Request errors

HTTP	Code	Retry?	What to do
401	`missing_api_key`	No	Add the `X-API-Key` header.
401	`invalid_api_key`	No	The key is unknown or revoked — fix or reissue it.
404	`no_match` or endpoint-specific refusal	No	The symbol or requested inventory item was not found. The body is the same flat refusal envelope as other tool refusals.
413	`request_too_large`	No	The JSON body exceeded the 64 KiB request cap or nesting guard. Shrink the body.
422	validation error / `invalid_request`	No	Schema 1 returns FastAPI `detail`; schema 2 returns a typed `invalid_request` envelope with `errors[]`.
429	`rate_limit_exceeded`	Yes	Per-minute rate exceeded — back off a few seconds.
429	`quota_exhausted`	After reset	Daily/monthly quota used up — wait for the window to reset.
5xx	—	Yes	Transient server/upstream issue — retry with backoff.

HTTP refusals are not wrapped in { "error": ... }. Schema-2 failures use typed envelopes; legacy schema-1 requests can still use the frozen flat value-refusal shape:

HTTP 413

{ "available": false, "reason": "request_too_large" }

Schema 1 validation errors follow FastAPI’s validation shape, so you can log exactly which field was wrong:

HTTP 422

{
  "detail": [
    { "loc": ["body", "periods"], "msg": "Input should be less than or equal to 20", "type": "less_than_equal" }
  ]
}

Schema 2 validation errors use the schema-2 envelope:

Schema 2 HTTP 422

{
  "data": {
    "unavailable": "invalid_request",
    "recovery": { "action": "none", "note": "correct the params named in errors and resubmit" },
    "errors": [{ "param": "periods", "given": 99, "expected": "Input should be less than or equal to 20" }]
  },
  "meta": { "schema_version": "2" }
}

See Errors and retries for a retry loop, and Plans and limits for the two 429 windows.

Refusal reasons

Refusals are not in the table above — they live inside a 200 and are enumerated by the API itself. Fetch the catalog at runtime instead of hard-coding:

stock_reference catalog=refusal_tokens (trimmed)

{
  "catalog": "refusal_tokens",
  "items": [
    { "code": "AMBIGUOUS_CANDIDATE", "public": "ambiguous_candidate",
      "recovery_action": "use_full_document",
      "note": "Fact-level candidates survived extraction guards but no single number was provable; inspect the filing when an accession is provided." },
    { "code": "CASH_RETURN_UNAVAILABLE", "public": "cash_return_unavailable",
      "recovery_action": "use_full_document",
      "note": "A cash-return operand is not a genuinely-tagged value; serving 0 would be a wrong number, so the yield refuses honestly instead." },
    { "code": "NOT_APPLICABLE_FOR_SHAPE", "public": "not_applicable_for_shape",
      "recovery_action": "use_alternative_field",
      "note": "The statement shape structurally lacks this line; use the named shape-native analog when provided." }
  ]
}

Each entry maps a refusal token to a recovery action and a human note. Common field-level reasons include not_reported (the concept was not tagged in the filing), not_applicable_for_shape (the statement shape structurally lacks that line), and cash_return_unavailable; tool-level reasons include no_match, no_insider_filings, and no_tracked_holders.

Get started

Guides

Agents

MCP

Reference

Request errors

Refusal reasons

​Request errors

​Refusal reasons

Request errors

Refusal reasons