Skip to content

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"}}
  • code is stable: branch on it. New codes may be added; treat one you do not know by its HTTP status.
  • message is for people: it names the parameter or the product at fault, and may change.
  • requestId is also in the X-Request-Id header 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 (reason not keeping up with the stream); it is not over a limit and can reconnect at once with since.

To stay well inside your limits:

  • Follow changes on the stream, not by polling REST. One stream carries every product you list.
  • Use ETag and If-None-Match on single events, scoresheets and gradings, and updatedSince on 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 with 1013) while a server starts or re-syncs: retry after a few seconds.
  • Servers restart for deploys. A stream closes with 1012 and the reconnect lands on another server, where since still works.
  • A product's feed.status turns degraded when its data may be stale: suspend its open markets until ok.
  • When the sportsbooks' lines cannot be kept current, only the books' markets are suspended, each one, until they are again; feed.status stays as it is.
  • GET /v1/health answers 200 with {"status": "ok"} while the API serves, and 503 with {"status": "starting"} while it starts. It needs no key; with yours, it also lists each of your products with ready, status and events.