Errors

Every answer has the same outer shape, so one piece of code reads all of them.

Success envelope

JSON

{
  "success": true,
  "data": [],
  "meta": {
    "request_id": "req_8f2c41d09b7e4a6f",
    "mode": "test",
    "next_cursor": null,
    "total": 0
  }
}

meta.mode is test or live, from your key. meta.request_id is also sent as the X-Request-Id header.

Error envelope

JSON

{
  "success": false,
  "error": {
    "code": "invalid_key",
    "message": "That key isn’t valid. It may have been revoked or rotated."
  },
  "meta": {
    "request_id": "req_8f2c41d09b7e4a6f",
    "mode": null
  }
}

Codes

Code	Status	When
missing_key	401	There is no Authorization header, or it is not “Bearer a54_…”.
invalid_key	401	The key is unknown, revoked, or past its grace period after a rotation.
not_found	404	No endpoint, game, creator or country lives at that address.
rate_limited	429	The key has made too many calls this minute. Retry-After says how long to wait.
api_unavailable	503	The API is switched off for a while. Try again later.

Handling them

Branch on error.code. The message is written for a person and may be reworded.
Retry a 429 after the seconds in Retry-After, and a 503 with a growing wait. Do not retry a 401 or a 404.
Log the request id. Quote it when you write to us and we can find the call.