Responses & Errors

Every SportQuanta endpoint returns JSON in one of two top-level shapes. Once you handle these two, you handle the whole API.

Success envelope

Successful responses wrap the payload in a data key:

{
  "data": { },
  "_meta": {
    "request_id": "req_01HX...",
    "served_from": "cache",
    "cache_ttl_seconds": 15
  }
}

data is an object for single-resource reads and an array for list endpoints.

Status	Used for
`200 OK`	Successful read.
`204 No Content`	Success with no body.

The `_meta` sidecar

Most data responses include a _meta object. It never affects your quota and is there purely for debugging and observability:

Field	Meaning
`request_id`	Unique id for the request. Include it in support tickets. Also returned as the `X-Request-Id` header.
`served_from`	`"live"` if freshly computed, `"cache"` if served from cache.
`cache_ttl_seconds`	Remaining TTL of the cached entry (or the TTL just set for a live response).
`provenance`	Source / ingestion metadata. Only present when you pass `?provenance=true`.

Free catalog endpoints omit _meta entirely, collapsing to a bare { "data": ... }.

Error envelope

Errors wrap a machine-readable object in an error key:

{
  "error": {
    "code": "snake_case_machine_readable",
    "message": "Human-readable, safe to display.",
    "details": null
  }
}

code — a stable, snake_case identifier. Safe to switch on in code; it does not change across releases.
message — human-readable text. May change for clarity, so don’t match on it.
details — null, or an object with field-specific context (validation errors, rate-limit retry hints, etc.).

Branch your error handling on error.code, never on error.message.

HTTP status codes

Status	Meaning
`400`	Malformed request — invalid JSON or a missing required parameter.
`401`	Missing, invalid, or expired API token.
`403`	Authenticated, but the token lacks the required scope.
`404`	The resource doesn’t exist, or you have no visibility into it.
`409`	Conflict.
`422`	Validation failure. `details` carries per-field errors.
`429`	Rate-limited or over quota. See the `Retry-After` header.
`5xx`	Server-side failure. Internal details are never echoed into `message`.

Common error codes

These codes are stable across releases. Switch on them in code.

`code`	Status	Meaning
`unauthorized`	`401`	Missing or invalid bearer token.
`insufficient_scope`	`403`	Token lacks the required scope.
`feature_not_in_plan`	`403`	Your plan tier doesn’t include the requested feature.
`unsupported_league`	`404`	The `{league}` path segment isn’t a league SportQuanta covers.
`endpoint_not_for_sport`	`404`	The league is valid but doesn’t expose this endpoint (e.g. play-by-play on a soccer league).
`data_not_yet_available`	`404`	The id is well-formed but the data hasn’t been ingested yet.
`invalid_query_parameter`	`422`	A query parameter failed validation.
`rate_limited`	`429`	Hourly rate limit exceeded. `Retry-After` header set.
`quota_exceeded`	`429`	Monthly quota exhausted.
`data_layer_unavailable`	`5xx`	Transient server-side data-layer failure.

See Rate Limits & Quota for the 429 codes and the details payloads they carry.

Empty results vs. errors

A list endpoint that finds no matching records returns 200 with an empty data array — not a 404. For covered leagues, an empty array can also mean the data hasn’t been ingested yet rather than that nothing exists. See Coverage → Data freshness for how to interpret this.

Get Started

Core Concepts

Success envelope

The `_meta` sidecar

Error envelope

HTTP status codes

Common error codes

Empty results vs. errors

​Success envelope

​The _meta sidecar

​Error envelope

​HTTP status codes

​Common error codes

​Empty results vs. errors

Success envelope

The `_meta` sidecar

Error envelope

HTTP status codes

Common error codes

Empty results vs. errors