Errors

Something in the query string is wrong. These are deterministic: the same request will fail the same way every time, so retrying is never the answer.

Three different refusals that are easy to confuse. 401 is who you are, 402 is what you hold, 403 is what the data permits — and only the second is fixed by money.

The route, the resource, or the method does not exist.

Both carry Retry-After, and it is authoritative.

Retry these, with backoff. Nothing about your request needs to change.

HTTP/1.1 401 Unauthorized

{
  "error": {
    "code": "unauthorized",
    "message": "Authentication required"
  }
}

unauthorized means the header was missing or empty on a route that costs credits. invalid_key means we read a credential and rejected it — unknown, malformed, revoked, expired, or belonging to a closed account. All five collapse into one code deliberately: telling them apart would help someone probing the key space and helps you not at all, because the fix is the same in every case. Check what you deployed. See Authentication.

HTTP/1.1 402 Payment Required

{
  "error": {
    "code": "insufficient_credits",
    "message": "This request needs 1 credit and your balance is 0.",
    "required": 1,
    "balance": 0,
    "top_up_url": "https://worldgovdata.com/account/billing"
  }
}

Nothing was served and nothing was charged. Do not retry — a 402 is not transient. Stop the loop, record where you stopped, top up, and re-send the identical request. Full handling advice on Credits.

HTTP/1.1 403 Forbidden

{
  "error": {
    "code": "display_only",
    "message": "Indicator 'oecd.example_series' is display-only: viewable on the portal with attribution, but not available for CSV/JSON export."
  }
}

This is the one refusal money cannot clear. The indicator’s provider permits display but not redistribution, so the value is visible on the portal and not exportable here. Check access_tier on the indicator record before you build a pipeline around a series. Licensing has the detail.

HTTP/1.1 400 Bad Request

{
  "error": {
    "code": "too_many_rows",
    "message": "Query matches 412903 rows, over the 100000 limit. Narrow by countries or year range."
  }
}

The message carries the real count, which is what makes it actionable — divide it by 100,000 and you know how many chunks you need. Nothing was served and no credits were spent: the count runs before any data is read. Pagination has a complete chunking recipe.

HTTP/1.1 429 Too Many Requests
Retry-After: 37
Cache-Control: no-store
X-Request-Id: 0f3a91c4e2b7
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1785315600

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded.",
    "retry_after": 37
  }
}

Sleep for Retry-After seconds, then retry the same request. It costs no credits. A correct backoff, in five languages, is on Rate limits.

A 500 never leaks a stack trace, a SQL fragment or an internal hostname; what it does carry is a request id, which also appears in our logs. Retry with backoff. If it persists, send us the X-Request-Id from the response headers and we can find the exact request without you having to reproduce anything.

503 accounts_unavailable is a specific, expected state: the accounts layer is deploying or has not been migrated yet. The free catalogue endpoints keep working throughout, by design — a deploy of the metering layer never takes the data API down.