Response Format & Status Codes

The V1 response envelope, status groups, error shapes, and cache TTLs.

Every V1 endpoint returns the same envelope so you can write one parser for the whole API.

Envelope

{
  "success": true,
  "type": "live",
  "cacheHit": false,
  "sport": "football",
  "data": { ... }
}

Field	Type	Meaning
success	boolean	true for any 2xx response.
type	string	Endpoint identifier, e.g. live, game, standings, brackets, search.
cacheHit	boolean	true when served from the in-memory cache. Useful for monitoring.
sport	string	Sport slug (only on sport-scoped endpoints).
data	object	Endpoint-specific payload. Most payloads also carry lastUpdateId, requestedUpdateId, and ttl.

data envelope extras

Many endpoints share these helper fields inside data:

{
  "lastUpdateId": 5677082919,
  "requestedUpdateId": -1,
  "ttl": 30,
  "sports": [],
  "countries": [],
  "competitions": [],
  "competitors": []
}

• lastUpdateId lets you skip identical payloads on the next poll by passing ?lastUpdateId=....
• ttl is the suggested seconds before re-requesting.
• sports / countries / competitions / competitors are denormalized lookups so a single response can render without follow-up calls.

Status groups

statusGroup on every game object summarizes phase:

Value	Meaning
1	Upcoming / not started
2	Postponed / cancelled
3	Live / in progress
4	Ended

statusText is the human label (Scheduled, Halftime, 1st Half, Ended, …) and shortStatusText is the compact form (FT, HT, 1H, LIVE).

Datetimes

All V1 datetimes are ISO 8601 with timezone offset:

2026-04-04T14:15:00+00:00

(V2 uses Unix epoch in startTimestamp — that’s a V2-only convention.)

Errors

Errors come straight from the backend without wrapping, with the matching HTTP status:

{ "success": false, "error": "Game not found", "code": 404 }

HTTP	Cause
400	Bad parameter (e.g. invalid date format)
401	Missing or invalid x-api-key
403	Key valid but plan does not cover the endpoint
404	Entity not found
429	Rate limit exceeded — back off and retry
5xx	Upstream issue — pass through to the user verbatim

See Error Handling for retry and backoff guidance.

Cache TTLs

The server caches every response. Public TTLs:

Endpoint family	TTL
Live / current scores	5s
Game detail	10s
Competition games / results	30s
Search	30s
Standings, brackets, stats	60s
News, transfers	60s
Competitions, countries	60s
Sports list	300s

cacheHit: true means you hit cache. To force a fresh request, vary a query param (?_=Date.now()), but please don’t — the cache is what keeps the API fast.

Pagination

Endpoints that paginate return a paging object inside data:

{
  "paging": {
    "previousPage": 0,
    "nextPage": 2,
    "currentPage": 1,
    "totalPages": 6
  }
}

Pass ?page=N (zero-indexed) to advance.