Reference

Errors

Every error from API V2 uses the same JSON shape and the matching HTTP status code.

Error format

{
  "error": {
    "code": "authentication_required",
    "message": "A bearer token is required.",
    "requestId": "req_0123456789abcdef"
  }
}

code is stable and meant for programs. Branch on it, not on message.
message is for people and may change.
requestId is also sent in the X-Request-Id header. Quote it when you ask for help.

Status	Code	Meaning
`401`	`authentication_required`	The request needs a bearer token and none was sent.
`401`	`invalid_token`	The token is malformed, wrongly signed, expired, issued for another environment, or not an API V2 access token (API V1 tokens and developer keys are not accepted).
`401`	`token_revoked`	The session behind the token was ended, or the user signed out everywhere or changed their password after the token was issued. Sign in again.
`404`	`not_found`	The route or resource does not exist.
`405`	`method_not_allowed`	The HTTP method is not supported here. The `Allow` response header lists the supported methods.
`500`	`internal_error`	An unexpected error occurred. Retry later and report the `requestId` if it persists.
`503`	`maintenance`	The API is in maintenance mode. Wait for the number of seconds in the `Retry-After` header.
`503`	`authentication_unavailable`	Tokens cannot be checked right now. Retry shortly. API V2 also answers this while its sign-in is not available yet, so every token receives it today.

Responses with status 401 also include a WWW-Authenticate: Bearer header.

On 401, do not retry with the same token. For invalid_token and token_revoked, sign in again to obtain a new one (see Authentication).
On 503, wait for Retry-After when it is present, otherwise back off and retry.
Do not retry 404 and 405 without changing the request.

Symptom	Likely cause
`authentication_required` although you sent a token	The header must be `Authorization: Bearer <token>`, with the word `Bearer` and a space.
`invalid_token` with a token that worked before	The token has expired (API V2 access tokens are short-lived), was altered, was issued for another environment, or is an API V1 token or developer key, which API V2 does not accept.
`not_found` on an endpoint you expect	Only the endpoints in the API reference exist on API V2. Aircraft, airport and performance calls are still on API V1.
The browser blocks a request with a CORS error	Check that you are calling an API server (see the introduction) and not this documentation site.
Different results on Test and Production	The Test API runs pre-release code. It uses the same live database, so the data is identical.

If the problem persists, report the requestId of the failing response.