API Error Codes - HTTP Status Codes & Error Handling

Error Format

Most error responses return a JSON object like:

{
  "error": 401,
  "message": "invalid apiKey",
  "code": "invalid_api_key"
}

Field	Type	Description
`error`	integer	HTTP status code
`message`	string	Human-readable description
`code`	string	Machine-readable reason code

Rate Limit Headers

All endpoints protected by the rate limiter return these headers:

Header	Description
`X-RateLimit-Limit`	Requests allowed per window (per apiKey)
`X-RateLimit-Remaining`	Requests left in the current window
`X-RateLimit-Reset`	Unix timestamp when the window resets

If you hit the limit (429), you also receive:

Header	Description
`Retry-After`	Seconds to wait before retrying

Common Error Responses

400 — Bad Request

{
  "error": 400,
  "message": "Invalid filters.",
  "code": "invalid_filters"
}

Used for syntactically valid requests with invalid parameters.

401 — Unauthorized

Missing or invalid apiKey.

{
  "error": 401,
  "message": "missing apiKey",
  "code": "missing_api_key"
}

{
  "error": 401,
  "message": "invalid apiKey",
  "code": "invalid_api_key"
}

403 — Forbidden

Valid API key, but no access to this channel or feature.

{
  "error": 403,
  "message": "Access denied: apiKey is not allowed to access this endpoint.",
  "code": "channel_not_allowed"
}

422 — Validation Error

Usually returned by FastAPI’s internal validation.

{
  "error": 422,
  "message": "Validation error",
  "code": "validation_error",
  "details": [
    {
      "loc": ["query", "fixtureId"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

429 — Rate Limit Exceeded

Triggered when request volume exceeds limits per apiKey.

{
  "error": 429,
  "message": "rate limit exceeded",
  "code": "rate_limited",
  "limit": 30,
  "windowSec": 1,
  "retryAfterSec": 1,
  "endpoint": "/fixtures/odds",
  "method": "GET"
}

Headers:

Retry-After: 1
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1700000000

503 — Service Unavailable

If internal systems (e.g. rate limiter) are unavailable:

{
  "error": 503,
  "message": "rate limiter unavailable",
  "code": "rate_limiter_error"
}

Notes

code is stable and suitable for programmatic handling.
message may change (but is designed to help developers).
Most endpoints return 429 if rate-limited — check your headers.
FastAPI validation errors are always returned as 422.

Getting Started

Reference

API Error Codes - HTTP Status Codes & Error Handling

Error Format

Rate Limit Headers

Common Error Responses

400 — Bad Request

401 — Unauthorized

403 — Forbidden

422 — Validation Error

429 — Rate Limit Exceeded

503 — Service Unavailable

Notes

​Error Format

​Rate Limit Headers

​Common Error Responses

​400 — Bad Request

​401 — Unauthorized

​403 — Forbidden

​422 — Validation Error

​429 — Rate Limit Exceeded

​503 — Service Unavailable

​Notes

Error Format

Rate Limit Headers

Common Error Responses

400 — Bad Request

401 — Unauthorized

403 — Forbidden

422 — Validation Error

429 — Rate Limit Exceeded

503 — Service Unavailable

Notes