Errors

Every error from the Application API, the Management API and the User API has the same JSON shape:

{
  "error": "not_found",
  "message": "user not found",
  "documentation_url": "https://docs.authalla.com/docs/errors#not_found"
}

Branch on error: the codes below are part of the API contract and only change with a new API version. message is written for people and can change at any time. documentation_url links to the code's section on this page.

A request whose parameters or body don't match the OpenAPI spec is rejected with validation_error before the API acts on it.

The OAuth2 endpoints, such as /oauth2/token, return standard OAuth2 errors (error and error_description) instead. See OAuth2 & OIDC.

bad_request

HTTP status: 400 · Returned by: Application API, Management API

The request couldn't be processed: the body isn't valid JSON, or a value breaks a rule the schema can't express.

Fix: Read message, which names the problem, and correct the request.

validation_error

HTTP status: 400 · Returned by: Application API, Management API, User API

The request doesn't match the OpenAPI spec: a required field is missing, a value has the wrong type, or it's out of range.

Fix: Compare the request with the operation's schema in the API reference. message names the failing parameter or field.

invalid_theme

HTTP status: 400 · Returned by: Management API

A theme value is invalid, for example a colour that isn't a hex code.

Fix: Read message, correct the value, and send the whole theme again.

unauthorized

HTTP status: 401 · Returned by: Application API, Management API, User API

The credential is missing, malformed, expired, or revoked.

Fix: Send Authorization: Bearer <credential>. For the Application API, request a new client_credentials token. For the Management API, check that the account API key hasn't been revoked.

forbidden

HTTP status: 403 · Returned by: Application API, Management API, User API

The credential is valid but doesn't permit this request: it lacks the required scope, it isn't allowed to act on this tenant, the operation needs an account-global key, or the token isn't a client_credentials token.

Fix: Read message. For a missing scope it names the scope; grant it to the app or key. Each operation's required scope is listed in the API reference.

not_found

HTTP status: 404 · Returned by: Application API, Management API, User API

The resource doesn't exist, or it isn't visible to this credential.

Fix: Check the ID and that it belongs to the tenant or account the credential is bound to.

conflict

HTTP status: 409 · Returned by: Application API, Management API

The request clashes with existing state, for example a user with that email already exists or the tenant already has a custom domain.

Fix: Fetch the existing resource and update it instead, or remove it first.

internal_error

HTTP status: 500 · Returned by: Application API, Management API, User API

Something failed on Authalla's side.

Fix: Retry with exponential backoff. If it persists, contact support with the time of the request.