API documentation

Errors

All errors share the same shape. Branch your logic on code, never on message.

Shape

400 Bad Request

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid parameter `limit`: Number must be less than or equal to 100"
  }
}

code is stable and part of the contract. message is written for the human debugging: it may be rewritten, translated or clarified at any time. A client that tests the message breaks on the first typo fix.

Codes

Codes
Code	Status	Meaning
`invalid_request`	400	A parameter failed validation. The message names which one.
`invalid_cursor`	400	The cursor is unreadable. Pass `page.nextCursor` back verbatim.
`unauthorized`	401	No key was sent, or the header is not in `Bearer` form.
`invalid_key`	401	The key is malformed or unknown.
`key_revoked`	401	The key existed but has been revoked. Create a new one.
`insufficient_scope`	403	The key does not carry the scope this operation requires.
`account_suspended`	403	The account is suspended and cannot use the API.
`cors_not_supported`	403	Called from a browser origin. This API is called from a server.
`not_found`	404	The resource does not exist, or is not public.
`rate_limited`	429	Rate limit reached. See `Retry-After`.
`internal_error`	500	A fault on our side. It has been logged.
`query_unavailable`	503	The query cannot be served right now — a storage index is building. Retry.

What to retry

429 and 503 are temporary: retry, honouring Retry-After when present. 400, 401, 403 and 404 are not — retrying unchanged returns the same answer.