All errors follow a consistent JSON structure with a stable machine-readable code, a human-readable message, and a request ID you can quote to support.
Error response format
{
"error": {
"code": "tier_insufficient",
"message": "Your plan doesn't include NBA real-time tier.",
"request_id": "req_8f3a2b1c",
"documentation_url": "https://sportapidata.com/docs/concepts/errors#tier_insufficient",
"param": "sport"
}
}
code — stable identifier; safe to switch on in code
message — human-readable; may change over time, do not switch on
request_id — include when contacting support
param — present when a specific parameter caused the error
documentation_url — deep link to the error in our docs
HTTP status codes
Status
Meaning
200
Success
400
Bad request — fix the request and retry
401
Unauthorized — invalid or missing API key
403
Forbidden — tier insufficient or resource restricted
404
Not found — resource doesn't exist
409
Conflict — idempotency-key clash, or duplicate webhook
422
Unprocessable — request shape OK, but semantically invalid
429
Rate limited — back off and retry
500
Server error — retry with exponential backoff
503
Service unavailable — partial outage, check status page
Error code reference
Code
Status
Description & resolution
unauthorized
401
API key missing, malformed, or revoked. Check the Authorization header.
tier_insufficient
403
The endpoint requires a tier your plan doesn't include. Upgrade or scope down.
scope_denied
403
Restricted key tried to access a resource outside its scope.
resource_not_found
404
The path is valid but no resource with the given ID exists.
invalid_parameter
400
One of your query params is malformed. Check param for which one.
missing_parameter
400
A required parameter is missing.
idempotency_conflict
409
Same idempotency key used with a different body. Use a new key.
rate_limited
429
Slow down. Honour retry_after_seconds.
internal_error
500
We had a problem. Retry with backoff. Persisting? Open a support ticket.