Skip to content

Errors

This page helps you handle the errors the Admin API and the Account API answer.

Every error comes back as a JSON body with error_code and error_description:

{
"error_code": "handler.settings_email.smtp_host_required",
"error_description": "SMTP host is required."
}

Decide what to do from the HTTP status first: a 4xx is something your request can fix, and a 5xx is a problem on the server. Then read error_code for the specific case, and show or log error_description.

  • error_code is a stable identifier for the failure, and it’s never translated. It’s either an UPPER_SNAKE code from the table below, or the key of the refusal’s sentence in the auth server’s text catalogs, in dotted lowercase, such as validator.email.invalid_format. The operations on clients, users, groups, resources, legal documents and settings answer a refused value with its key, such as handler.client.identifier_in_use or handler.settings_general.issuer_uri_invalid, so you can tell which field to fix. A few refusals keep a code of their own from the table, such as EMAIL_TOO_LONG, VALUE_TOO_LONG and EMAIL_ALREADY_EXISTS.
  • error_description is a sentence for people. Don’t match on it: the wording and the language can change, the code won’t.
  • error_field, on a refusal of one member of the request body, is a JSON Pointer to it, such as /palette/light/brand or /footerLinks/1/url, for a brand or an email template. Its index counts from 0, while the sentence counts from 1. It’s left out otherwise.

A refusal of a value you sent, a 400 or 409 such as VALIDATION_ERROR, comes in the request’s language: the ui_locales query parameter, or else the Accept-Language header, when the auth server has the sentence in that language. The rest are in English: a refused access token, a body that doesn’t parse, a malformed id, and every other status. The refusal at the top of this page, sent with Accept-Language: pt-BR:

{
"error_code": "handler.settings_email.smtp_host_required",
"error_description": "O host SMTP é obrigatório."
}

The protocol endpoints, /auth/authorize, /auth/token, /auth/revoke, /auth/introspect, /connect/register and /userinfo, answer errors in the format their standards define, not this one. Authorize, Token, Revoke, Introspect and UserInfo cover theirs, and Dynamic client registration the registration endpoint’s.

This is every UPPER_SNAKE code the two APIs answer.

Code Status Meaning
VALIDATION_ERROR 400 A value was refused. error_description says which and why.
INVALID_REQUEST_BODY 400 The body isn’t the JSON the operation expects.
INVALID_REQUEST 400 The Authorization header or the access_token parameter was sent twice, the token was sent two ways at once, or a form body doesn’t parse.
EMAIL_TOO_LONG 400 The new user’s email address is longer than 254 characters.
VALUE_TOO_LONG 400 A user attribute’s value is longer than 250 characters.
FILE_TOO_LARGE 400 The profile picture or client logo is over the size limit, or an upload’s body isn’t a multipart form. A brand’s file over its limit answers validator.image.too_large or validator.font.too_large.
NO_FILE 400 A profile picture or client logo upload has no picture field, or a brand’s file upload has no file field.
AUTHENTICATION_FAILED 400 The password sent to confirm a password change, an email change, turning two-factor authentication on or off, a new set of recovery codes, or deleting the account is wrong. For two-factor authentication, a new set of recovery codes and deleting the account, a missing password answers it too.
OTP_CODE_REQUIRED 400 Two-factor authentication was turned on without a code, or an account with two-factor authentication on was deleted without an authenticator code or a recovery code.
INVALID_OTP_CODE 400 The code isn’t six digits, or it doesn’t match the authenticator.
OTP_CLOCK_AHEAD 400 The code is the authenticator’s next one, from 30 seconds ahead: the device’s clock runs ahead of the auth server’s. Nothing was spent, so ask the user to check that the device sets its time automatically and send the code it shows.
INVALID_RECOVERY_CODE 400 The recovery code sent to delete the account, in place of an authenticator code, is wrong or was already used. Nothing was deleted, and no code was spent.
OTP_ENROLLMENT_NOT_PENDING 400 No enrollment is pending, or it expired. Start a new one with GET /api/v1/account/otp/enrollment.
SECRET_KEY_NOT_ACCEPTED 400 The request sent a secretKey. Start an enrollment and send only the code from the authenticator.
OTP_ALREADY_ENABLED 400 Two-factor authentication is already on.
OTP_NOT_ENABLED 400 Two-factor authentication is already off.
INVALID_OR_EXPIRED_VERIFICATION_CODE 400 The email verification code is wrong or has expired.
SMTP_NOT_ENABLED 400 The operation needs to send email, and SMTP is off: a test email, or sending or checking an email verification code.
SEND_FAILED 400 The test email couldn’t be sent. error_description says what to check.
ACCESS_TOKEN_REQUIRED 401 No access token was sent.
INVALID_TOKEN 401 The token is malformed, expired, revoked, not an access token for authserver, from another issuer, its grant was revoked, or its client, user or session is gone or disabled. Or a DPoP-bound token was sent as Bearer, a token bound to no key was sent with DPoP, or its proof is signed by another key.
INVALID_DPOP_PROOF 401 The token was sent with the DPoP scheme, and its proof is missing, sent twice, fails a check or was already used. Make a new proof and retry.
INSUFFICIENT_USER_AUTHENTICATION 401 The token’s sign-in is too old, or below the level the operation needs. Downloading the account’s data needs a sign-in in the last 300 seconds at urn:goiabada:level2_optional or above. Sign the user in again and retry with the new token. See Authentication.
INVALID_SESSION 401 On POST /api/v1/account/logout-request: the token carries no session id (sid), its session is gone, or the token’s client isn’t part of that session.
INSUFFICIENT_SCOPE 403 The token carries none of the scopes the operation accepts. The WWW-Authenticate header says error="insufficient_scope".
USER_CONTEXT_REQUIRED 403 An Account API call was made with a token that wasn’t issued for a user, such as one from the client credentials flow, carrying authserver:manage-account. Without it, the answer is INSUFFICIENT_SCOPE.
CLIENT_NOT_ALLOWED 403 The operation answers only tokens issued to the admin console’s own client, so no other client reaches it, whatever its scopes. Deleting the account and downloading its data are the two. The WWW-Authenticate header says error="insufficient_scope".
ACCOUNT_DELETION_DISABLED 403 The account can’t be deleted by its user, because an administrator turned that off. An administrator can still delete it.
FORBIDDEN 403 The token is valid, but the consent or session it names belongs to another user.
MANAGE_SCOPE_REQUIRED 403 The request acts on an administrator or an administrative permission, which only authserver:manage may do. See Administrators.
NOT_FOUND 404 Nothing has that id.
CONCURRENT_UPDATE 409 Another request changed what yours was based on. Nothing was saved: read it again and retry.
EMAIL_ALREADY_EXISTS 409 Another user already has that email address.
LAST_ADMINISTRATOR 409 The change would leave no enabled user holding authserver:manage, a user deleting their own account included. Grant it to another user first.
ROTATION_IN_PROGRESS 409 Another signing key rotation won the race, and this call rotated nothing. Don’t retry: the rotation it ran into already happened.
ROTATION_OUTCOME_UNKNOWN 409 Saving a signing key rotation failed at its very end, so it may or may not have happened. List the keys before rotating again: it happened if the key that was next is now current. error_description ends with a request id, as for INTERNAL_SERVER_ERROR. See The key set.
TOO_MANY_REQUESTS 429 A rate limit was reached. The Retry-After header says how many seconds to wait.
INTERNAL_SERVER_ERROR 500 The request failed inside the server. error_description ends with a request id an operator can find in the server’s log. Retrying is reasonable.
KEY_SET_INCOMPLETE 500 A signing key rotation found no current or no next key. That’s a deployment problem a retry won’t clear. error_description ends with a request id, as for INTERNAL_SERVER_ERROR.

An operation that replaces a whole list, such as a client’s redirect URIs, its sign-out redirect URIs or a user’s groups, also takes the list as you last read it, in a field named expected and the list’s name, such as expectedRedirectURIs or expectedPostLogoutRedirectURIs. When the stored list is no longer that one, because someone else saved it in between, the save is answered 409 with CONCURRENT_UPDATE and changes nothing. Read the list again, apply your change to it, and save again.