Skip to content

docs: add not_ready + offset_too_large to canonical error table #193

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Mlaz-code merged 1 commit into from
Apr 24, 2026
Merged

docs: add not_ready + offset_too_large to canonical error table #193

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion content/en/api-reference/conventions.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 2 additions & 0 deletions content/en/api-reference/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |

<Callout type="info">
Expand Down