Response format

All routes share one envelope, so a single parser covers the whole API.

Success envelope#

Paginated routes add count, page, perPage, total and totalPages. Single-record routes return an object in data, not an array.

{
  "data": [ ... ],
  "count": 10,
  "page": 1,
  "perPage": 50,
  "total": 2141,
  "totalPages": 43,
  "source": "GZW Data API",
  "timestamp": "2026-09-20T08:00:00.000Z",
  "dataVersion": "2026-09-14T13:05:54.486874Z"
}

Timestamps

timestamp is the response time. dataVersion identifies the data snapshot. Example counts above are illustrative.

Error envelope#

HTTP errors share a stable shape: error.code, error.message, optional route details, plus source, timestamp and dataVersion.

Code	Meaning
`DATASET_NOT_FOUND`	Unknown dataset name
`RECORD_NOT_FOUND`	No record with that ID
`METHOD_NOT_ALLOWED`	The API is read-only; use GET
`RATE_LIMITED`	Too many requests. See limits
`INTERNAL_ERROR`	Unexpected server error

The full contract lives in API_CONTRACT.md and the OpenAPI document.