Best practices

Poll no faster than the book updates

Every entry on the Per-book coverage table and the update_interval_seconds field on GET /v1/bookmakers describe how often we poll a book. Polling faster than that only spends your request allowance and your plan’s speed limit for repeated, unchanged prices. Compare last_update between calls before treating a response as new.

Ask only for what you use

bookmakers and markets both narrow a response; eventIds narrows a list call to specific fixtures. A smaller response is faster to parse and does not change what counts against your allowance, since every odds, props or history call counts once regardless of size.

Read the rate-limit headers, do not guess them

Every response, including error responses, carries x-requests-used, x-requests-remaining and X-RateLimit-Remaining. Back off when X-RateLimit-Remaining reaches zero instead of waiting for a 429, and read Retry-After on a 429 rather than a fixed sleep. The Speed limits and Errors page lists every header and every error code.

Treat x-extensible-enum fields as open

error.code, size.kind, a bookmaker’s kind, and a plan name can all gain a new value within /v1, deliberately: the OpenAPI file marks each of these x-extensible-enum rather than a closed enum so a value your client does not recognize yet is still valid JSON, not a parse failure. Write the fallback branch now.

Never assume a book you asked for is in the response

A book with no price for a fixture is simply absent from bookmakers[]. A book that had a price but could not be safely matched to the fixture is named in unmatched_bookmakers[] instead of being dropped without a trace. Check both before concluding a book has no line.

Handle last_update: null

A null last_update means we do not yet measure a fetch time for that book; it is never an estimate and never means the price is old. Do not treat it as a missing or stale price.