API errors

The API answers a failed request in one of three shapes. Which one you get depends on the endpoint and on the kind of failure, and each carries a machine-readable code that is meant to be matched on. The human-readable text is not.

The standard shape

{
  "code": "E_NOT_FOUND",
  "status": 404,
  "reason": "not_found",
  "message": "Resource not found"
}

Some reasons you will meet:

The list is long, because every domain error has its own reason. These are examples, not the whole set.

Validation errors

A body that fails validation, a password that breaks the realm’s policy, a hash the server cannot accept and a locale that is not well formed all answer with 422 and a list. The list has one entry for each problem, so a form can show them all at once.

{
  "errors": [
    { "field": "username", "code": "length", "message": "username is required" }
  ]
}

This shape has no reason and no status in the body. Read the status from the response.

OAuth errors

The token endpoint, the device flow and some failures of the authorization request, such as a missing PKCE challenge, answer in the shape RFC 6749 defines, so that any OAuth library can read them.

{
  "error": "invalid_client",
  "error_description": "Client authentication failed."
}

The device flow adds the codes from RFC 8628: authorization_pending, slow_down, expired_token and access_denied, all with status 400.

What to match on

Branch on the status for the class of failure, then on the code for the specific one. Do not branch on message: it is English prose, its wording is not part of the contract, and some messages carry detail that changes from one request to the next.

One line reads the code out of any of the three shapes:

const body = await response.json()
const code = body.reason ?? body.error ?? body.errors?.[0]?.code

The console does the same. It picks the text it shows from reason, from error for an OAuth response, or from code for each entry of a validation error, in the language of the person using it, and falls back on message only when it has no text for the code. See Localization.