Responses & Errors

Success envelopes

REST reads return JSON with an outer data key. The payload inside it depends on the endpoint:

Family	Payload location
Catalog	`data` array.
Game schedule and Proto lists	`data.items`, with optional `data.next_cursor`.
Entity detail	Object in `data`.
Rosters and several soccer lists	Array in `data`.
Team directory and odds history	`data.items`.
Current odds/props, opening/closing, fair/best, CLV/movement	Additional `data` object: endpoint payload at `data.data`.
Baseball profile, snapshot, comparison, game-log, recap, prop edge; KBO/NPB bullpen, first-inning, NRFI, pitch-type convenience reads	Additional `data` object: `data.data`.
Settlements and divergence	Direct payload object in `data`.

Current game odds use this structure (illustrative empty payload):

{
  "data": {
    "data": {
      "game_id": "GAME_ID",
      "snapshot_at": "2026-10-13T00:00:00Z",
      "markets": {}
    }
  },
  "_meta": {
    "request_id": "req_example",
    "served_from": "live",
    "cache_ttl_seconds": 10
  }
}

Use the endpoint’s response schema instead of assuming every list is a bare array or recursively unwrapping every property named data. Canonical reads commonly use snake_case, while some soccer analytics and provider-derived statistics retain camelCase.

Metadata

`_meta` field	Meaning
`request_id`	Server-generated request identifier, also in `X-Request-Id`. Include it in support requests.
`served_from`	`live` for a freshly read/computed response or `cache` for a response-cache hit. This does not mean the fixture is live.
`cache_ttl_seconds`	Remaining cache TTL, or selected TTL on a fresh read. Omitted when zero. It does not measure upstream data age.
`provenance`	Per-field source, run ID, and ingestion time when requested and available.
`availability`	Endpoint-specific context, including soccer roster coverage.

Authenticated catalog handlers include _meta.request_id but generally omit cache metadata. Service metadata, token/tenant introspection, and public coverage have separate schemas and may omit _meta. The endpoint reference expands nested response attributes by default. For a directory, read data.items[] for the entity’s fields; for a single entity, read data. The generated response example also shows nested fields. Team and player views retain their canonical identity, names, league-specific attributes, timestamps, and asset metadata, then add a resolved logo_url or headshot_url. Soccer competition views and Proto mapped fixtures likewise retain their embedded canonical fields. These added fields do not replace the underlying entity. Optional fields may be absent; nullable fields or uninitialized collections can be null. Neither omission nor null means zero. Preserve numeric zero when explicitly present.

Errors

{
  "error": {
    "code": "data_not_yet_available",
    "message": "No data for that id has been ingested yet.",
    "details": { "league": "mlb" }
  }
}

Branch on error.code and HTTP status. Messages can change. details is optional and varies by code; it may be absent, null, or a context object.

Code	Status	Interpretation
`unauthorized`	401	Missing, malformed, invalid, or revoked bearer token.
`insufficient_scope`	403	Token does not permit this method; reads require `api.read`.
`feature_not_in_plan`	403	Missing capability or bookmaker access. Inspect `details.feature` and any parameter context.
`api_token_lookup_failed`	500	Token validation store could not be queried.
`unsupported_league`	404	League is not registered.
`endpoint_not_for_sport`	404	Valid league, unsupported endpoint or mode for that sport.
`data_not_yet_available`	404	Requested detail has not been ingested, or a live record is no longer fresh enough to serve.
`route_not_found`	404	Unknown route; non-billable.
`method_not_allowed`	405	Unsupported method; `Allow` lists permitted methods. Non-billable.
`invalid_query_parameter`	400 or 422	Invalid query value; status differs by handler.
`rate_limited`	429	Organization hourly bucket exhausted; honor `Retry-After`.
`quota_exceeded`	429	Organization request budget exhausted; inspect reset/budget details.
`data_layer_unavailable`	Usually 502	Read dependency failed or the deployment lacks the requested history capability.

See each operation for its statuses. The public reads do not share a general 204, 409, or field-validation response contract beyond these behaviors.

Empty and unavailable data

Empty results retain the endpoint’s own shape: data: [], data.items: [], data.data.markets: {}, or another documented collection. A successful list can be empty because of filters, ingestion coverage, an off-season, or a provider limitation. Soccer analytics can return data.available=false with a reason when a competition or measure cannot be resolved. KBL injury reads instead return data.availability="provider_unavailable" and data.reason="dated_injury_feed_not_exposed". These are successful availability responses, not evidence that every player is healthy. See IDs, Assets & Availability and Rate Limits & Quota before deciding whether to retry or count a response as complete.

Get Started

Core Concepts

Data & Integration

Agents

Success envelopes

Metadata

Errors

Empty and unavailable data

​Success envelopes

​Metadata

​Errors

​Empty and unavailable data

Success envelopes

Metadata

Errors

Empty and unavailable data