Error Codes

Reference for all API error codes and their meanings.

Error Response Format

All errors follow a consistent JSON format:

{
  "error": "error_code",
  "message": "Human-readable description of the error"
}

Code	Error	Description
`400`	`bad_request`	The request was malformed or missing required parameters
`401`	`unauthorized`	Invalid or missing API key
`403`	`forbidden`	Your plan does not include access to this endpoint
`404`	`not_found`	The requested resource does not exist
`429`	`rate_limit_exceeded`	Too many requests — see Rate Limits
`500`	`internal_error`	An unexpected server error occurred
`503`	`service_unavailable`	The API is temporarily unavailable

{
  "error": "bad_request",
  "message": "Invalid date format. Use YYYY-MM-DD."
}

{
  "error": "not_found",
  "message": "No race data found for 2025-12-25. Races are not held on this date."
}

{
  "error": "forbidden",
  "message": "WebSocket endpoints require an Ultimate plan. Please upgrade at /pricing."
}