DEVELOPER DOCUMENTATION

Limits and errors

Your first request, the API reference, and everything in between.

Get API key

Understand your allowance.

All keys on an account share a request allowance. Check your plan and usage in the dashboard.

Request limits

Rate limits use fixed minute windows. Monthly allowances reset at 00:00 UTC on the first day of each month. Requests admitted to the upstream service count towards usage, including provider failures.

Response headers
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-MonthlyLimit-Remaining: 49999

# On a rate-limited response:
Retry-After: 30

Read Retry-After before retrying a rate-limited request. See pricing if you need a larger allowance.

Handle errors

400
Invalid request

Check parameter names, ID values, and dates.

401
Authentication required

Your key is missing, invalid, expired, or revoked.

403
Access denied

The request origin or key scope is not allowed.

404
Not found

The endpoint or requested record does not exist, or the market is unsupported. Retired v1 read paths also answer 404.

410
Gone

The fixture was merged into another. Request the fixture in superseded_by. A retired v1 path behind the website gateway also answers 410, with a replacement field.

422
Invalid parameters

Check the endpoint’s parameter types and allowed combinations.

429
Limit reached

Read Retry-After before retrying.

503
Service unavailable

Retry with exponential backoff and respect Retry-After when present.

Errors from the website gateway use {"error":"message"}. API validation errors use a detail field. A 410 for a merged fixture has error, detail, superseded_by and merged_at. Check the endpoint reference for response schemas.

Keep responses manageable

Reference catalogues (/sports, /countries, /competitions, /channels, /broadcasters) are unpaginated lists. Only /competitions takes filters (sport_ids, country_ids); /channels and /broadcasters are scoped by market. The change feeds (/fixtures/merges, /channels/changes) page with since and limit. Fixture lists use cursors—see the global contract guide for pagination and date-range rules.