Errors & rate limits
Application errors use the standard envelope with data: null. message explains the error; request_id helps trace it.
JSON · 429
{ "code": 429, "message": "Rate limit exceeded", "request_id": "req_demo_001", "data": null }| HTTP status | Meaning | Action |
|---|---|---|
400 | Invalid request parameters | Check parameter names, required fields, pagination bounds, dates and timezone format. |
401 | Missing or invalid API key | Check the X-API-Key or Authorization header and key status. |
403 | Feature unavailable on your plan | Live scores require Pro or above. Match odds require Business. |
404 | Resource not found | Check the route and entity ID. Some subresources may have no data. |
429 | Rate limit or monthly quota exceeded | For rate limits, retry after Retry-After. For exhausted monthly quotas, wait for reset or upgrade. |
503 | Service temporarily unavailable | Retry with bounded exponential backoff. |
Parameter parsing errors
Malformed query values and unknown query parameters return HTTP 400 with a plain-text body from the request parser. These errors do not include the JSON envelope or request_id. Check the status and Content-Type before parsing an error response.
Text · 400
Failed to deserialize query string: unknown field
Rate limits and monthly quotas
Keys in the same account share quota and rate limits. Monthly quota resets on the first day of each month at 00:00 UTC. Requests rejected with 429 do not count toward monthly quota.
| Response header | Description |
|---|---|
X-RateLimit-Limit | Requests allowed per minute. |
X-RateLimit-Remaining | Requests remaining in the current minute. |
X-RateLimit-Reset | Seconds until the current minute window resets. |
X-Quota-Limit | Quota for the UTC calendar month. |
X-Quota-Remaining | Requests remaining this month. |
Retry-After | Seconds to wait, on 429 responses caused by the rate limit. |