Skip to main content

​
Error Format

Most error responses return a JSON object like: 
{
  "error": 401,
  "message": "invalid apiKey",
  "code": "invalid_api_key"
}
FieldTypeDescription
errorintegerHTTP status code
messagestringHuman-readable description
codestringMachine-readable reason code

​
Rate Limit Headers

All endpoints protected by the rate limiter return these headers:
HeaderDescription
X-RateLimit-LimitRequests allowed per window (per apiKey)
X-RateLimit-RemainingRequests left in the current window
X-RateLimit-ResetUnix timestamp when the window resets
If you hit the limit (429), you also receive:
HeaderDescription
Retry-AfterSeconds 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.