Errors and limits¶
The error format¶
Every REST error has the same body, and an HTTP status that matches its code:
{"error": {"code": "product_not_allowed", "message": "your key does not include 'props'", "requestId": "req_5f1c2a9e07b34d68"}}
codeis stable: branch on it. New codes may be added; treat one you do not know by its HTTP status.messageis for people: it names the parameter or the product at fault, and may change.requestIdis also in theX-Request-Idheader of every response, successful or not. Quote it when you contact support.
The stream reports the same errors as close codes; the close reason is the message.
Error codes¶
| Code | HTTP | Stream close | Meaning | What to do |
|---|---|---|---|---|
missing_key |
401 | 4401 |
No key sent | Send Authorization: Bearer <key> |
invalid_key |
401 | 4401 |
Unknown or revoked key | Check your key with us; do not retry |
product_not_allowed |
403 | 4403 |
Your key does not include that product | Ask without it, or ask us to add it |
bad_request |
400 | 4400 |
A parameter is not valid: an unknown id in periods, marketTypes, groups or gradingProducts, a malformed cursor, since or limit, a time in from, to or updatedSince that is not ISO 8601 with its zone, a confidence other than confirmed, a stream without products |
Fix the request; do not retry it as it is |
not_found |
404 | 4400 |
No such event, scoresheet, grading or route, or an unknown or unavailable product (on the stream, a product in products) |
Check the id, the path and the product |
method_not_allowed |
405 | — | The route exists, but only answers GET |
Use GET |
rate_limited |
429 | 4429 |
Over your requests per minute (REST), or over your connections or not keeping up (stream) | Wait the seconds in Retry-After (REST); see When the stream closes |
unavailable |
503 | 1013 |
Starting up or re-syncing | Retry after Retry-After (a few seconds) |
internal |
500 | 1013 when a stream is refused, 1011 when an open stream fails |
Our fault | Retry with back-off; send us the requestId if it goes on |
An unknown sport, league or event id in a filter is not an error: it matches nothing and gives an empty answer.
The stream's close codes, with when to reconnect, are in Connecting and resuming.
Limits¶
Your key sets two limits, counted across all our servers:
| Limit | Applies to | When you reach it |
|---|---|---|
| Requests per minute | Every REST request made with the key, 304 Not Modified answers included; /v1/health does not count |
429 rate_limited, with Retry-After: the seconds until the next minute starts |
| Open streams | WebSocket connections open at the same time | The new connection closes with 4429 (reason over your connection limit). Close another one, or wait 30 s and retry |
- The catalogs that need no key (
sports,periods,market-types,market-groups,stat-keys) do not count against your requests. - A stream client that falls too far behind is closed with
4429(reasonnot keeping up with the stream); it is not over a limit and can reconnect at once withsince.
To stay well inside your limits:
- Follow changes on the stream, not by polling REST. One stream carries every product you list.
- Use
ETagandIf-None-Matchon single events, scoresheets and gradings, andupdatedSinceon lists. - Send
Accept-Encoding: gzip. - Cache the catalogs for a day.
Retention¶
| What | Kept |
|---|---|
| Events and markets | While they are on a product's board |
| Scoresheets | 30 days after their last revision |
| Gradings | 7 days after their last revision |
Stream history for a resume with since |
The last 20 000 messages of each product on each server (5 000 for grading); from further back, or on a server that has just started, a fresh snapshot |
Availability¶
503 unavailable(or a stream closed with1013) while a server starts or re-syncs: retry after a few seconds.- Servers restart for deploys. A stream closes with
1012and the reconnect lands on another server, wheresincestill works. - A product's
feed.statusturnsdegradedwhen its data may be stale: suspend its open markets untilok. - When the sportsbooks' lines cannot be kept current, only the books' markets are
suspended, each one, until they are again;feed.statusstays as it is. GET /v1/healthanswers200with{"status": "ok"}while the API serves, and503with{"status": "starting"}while it starts. It needs no key; with yours, it also lists each of your products withready,statusandevents.