From 57f6f23768a0467dadd7b447981349aff94653b6 Mon Sep 17 00:00:00 2001 From: Mlaz-code <68407656+Mlaz-code@users.noreply.github.com> Date: Fri, 24 Apr 2026 11:24:07 -0400 Subject: [PATCH] docs(errors): add not_ready + offset_too_large to canonical table The overview error-codes table was missing two codes that the server already emits: offset_too_large (400, /odds and /odds/delta when offset exceeds 500) and not_ready (503, backing store not ready). Both are in the Python + TS SDKs; only the canonical docs table was behind. Also updates the count in conventions.mdx from "19 HTTP codes" to 21. --- content/en/api-reference/conventions.mdx | 2 +- content/en/api-reference/overview.mdx | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/content/en/api-reference/conventions.mdx b/content/en/api-reference/conventions.mdx index 6486800..ea8681a 100644 --- a/content/en/api-reference/conventions.mdx +++ b/content/en/api-reference/conventions.mdx @@ -102,7 +102,7 @@ Every non-2xx response returns a single `error` object. `missing_api_key`, `invalid_api_key`, `validation_error`, `tier_restricted`, `rate_limited`, `too_many_streams`, `not_found`, `upstream_error`, `internal_error`. -See the full list (19 HTTP codes + 6 WebSocket frame codes, with HTTP statuses) in [API Overview → Error Codes](/en/api-reference/overview#error-codes). `bad_request` and `invalid_request` are deprecated — both were collapsed into `validation_error`. +See the full list (21 HTTP codes + 6 WebSocket frame codes, with HTTP statuses) in [API Overview → Error Codes](/en/api-reference/overview#error-codes). `bad_request` and `invalid_request` are deprecated — both were collapsed into `validation_error`. ## Timestamps diff --git a/content/en/api-reference/overview.mdx b/content/en/api-reference/overview.mdx index cedd813..352fa50 100644 --- a/content/en/api-reference/overview.mdx +++ b/content/en/api-reference/overview.mdx @@ -333,12 +333,14 @@ Emitted in REST responses. | `gone` | 410 | Event has ended or expired — use `/api/v1/events` for current events | | `unknown_endpoint` | 410 | Wrong API path — response includes `correct_endpoint` with the right route (e.g. `/api/v1/arbitrage` → `/api/v1/opportunities/arbitrage`) | | `validation_error` | 400 | Request body or query parameters failed validation | +| `offset_too_large` | 400 | `offset` exceeds the per-endpoint maximum (currently 500 on `/odds` and `/odds/delta`). Switch to cursor-based pagination or advance `since` | | `rate_limited` | 429 | Per-minute request rate limit exceeded — response includes `retry_after` | | `concurrent_request_cap` | 429 | Too many in-flight requests for your tier — reduce parallelism or upgrade | | `too_many_streams` | 429 | Maximum concurrent SSE or WebSocket streams exceeded for this API key | | `backpressure` | — | Emitted as an SSE `event: error` (not an HTTP status) when the client cannot keep up; server then closes the stream | | `upstream_error` | 502 | Temporary issue reaching an upstream sportsbook or auth provider | | `service_unavailable` | 503 | A required service (e.g. key management) is not configured or is offline | +| `not_ready` | 503 | A backing store the endpoint depends on (e.g. ClickHouse, closing-line capture) is not yet ready to serve the request. Retry with backoff | | `internal_error` | 500 | Unexpected server error — retry with backoff and contact support with `X-Request-Id` if it persists |