Every error is an RFC 9457 problem document with a stable code. Branch on the code and show the detail to a person: titles and details may be reworded, while codes and statuses keep their meaning.
bad_requestThe request could not be read.
Retry: No
unauthorizedNo key, or an unknown key; or an OAuth access token that is unknown, expired or revoked, or whose account has no live key (detail: "sign in again", with a WWW-Authenticate: Bearer challenge).
Retry: No; sign in again
attestation_requiredThe account has no current OPRA subscriber attestation: none, or one on an older release of the subscriber agreement; detail then names the current release.
Retry: No; attest first (sign the current release)
attestation_pendingThe account is not attested yet and support has given it grace: finished sessions only, and this request may carry today's data (a live endpoint, the stream, no date, or a range open at the top). detail: "Your access is limited to finished sessions until your OPRA attestation is complete."
Retry: No; ask for a finished session, or attest
plan_endedThe plan ended (plan_until on /v1/status, plus a day for a renewal to land) and the account is a professional subscriber: no data, on any endpoint or the stream, until the plan is renewed; detail names the date. A non-professional whose plan ended is not refused: the key reads as the Free plan.
Retry: No; renew on the site
key_revokedThe key was used from too many addresses or devices.
Retry: No; contact support
history_out_of_reachThe session asked for is before the tier's reach; X-History-Earliest says the first allowed. Every date the request names counts and the oldest decides, in either date form (2026-10-22 or 20261022).
Retry: No; ask for a later session
export_not_in_tier/v1/export is a Quant right.
Retry: No
symbol_not_in_tierdetail: "your plan doesn't include this symbol" (Free reaches a limited set).
Retry: No; a plan with every symbol
compatible_api_not_in_planThe request came through one of the compatible APIs and the key's plan has none (Free, Basic, Trader); that API answers in its own error shape with this detail, which names the plan and the plans that include them. The key's own /v1 rights are unchanged.
Retry: No; Developer and Quant include them
no_such_session/v1/sessions/{date}: the day is not a listed finished session.
Retry: No; pick a date from GET /v1/sessions
unknown_symbolNo listed options for that root.
Retry: No
no_data, no_history, no_aggregates, no_export, no_such_dataset, file_missing, not_foundNothing recorded for what was asked (a session, a symbol-day, an export dataset).
Retry: No, unless the session is still being prepared
not_builtA finished session's playback answer or chain file is not ready yet; asking queues it. The body carries ready_by (RFC 3339 UTC, when it is expected) and queue_position (requests ahead, counting this one), and Retry-After is sent.
Retry: Yes, after Retry-After
not_availablehistory/chain: the session is before the earliest day a chain file can be built; nothing is queued.
Retry: No
no_sessionThe date asked for fell on a weekend or a market holiday: there was no session, so nothing is owed.
Retry: No: pick a session day
invalid_date/v1/sessions/{date}: the path date is not YYYY-MM-DD.
Retry: No; fix the date
invalid_parameter, invalid_range, range_too_long, unknown_part, unknown_interval, one_session_per_call, finished_session_requiredA parameter is missing, out of range or not served in this combination; detail names it.
Retry: No; change the request
rate_limitedOver the key's rate and burst; RateLimit-* and Retry-After are sent.
Retry: Yes, after Retry-After
address_rate_limitedOver the address's ceiling across keys.
Retry: Yes, after Retry-After
quota_reached_dayThe tier's API calls for the New York day are spent; Quota-* and Retry-After (seconds to midnight New York) are sent. The website's requests for you never count.
Retry: Yes, after Retry-After
too_many_in_flightToo many heavy reads (chain files, session ranges, exports) at once for this key.
Retry: Yes, after Retry-After, when one finishes
busy_loading_sessionsToo many past sessions are being prepared at once.
Retry: Yes, after Retry-After
temporarily_unavailableThe service is briefly unavailable; Retry-After is sent.
Retry: Yes, after Retry-After
plans_unavailableGET /v1/plans while the plan table is briefly unavailable.
Retry: Yes, after Retry-After
audit_unavailableData access is temporarily unavailable.
Retry: Yes, retry later
timeoutThe answer took longer than its time limit.
Retry: Narrow the request (fewer sessions, strikes or expirations), then yes