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.
The fields
Section titled “The fields”error_codeis a stable identifier for the failure, and it’s never translated. It’s either anUPPER_SNAKEcode from the table below, or the key of the refusal’s sentence in the auth server’s text catalogs, in dotted lowercase, such asvalidator.email.invalid_format. The operations on clients, users, groups, resources, legal documents and settings answer a refused value with its key, such ashandler.client.identifier_in_useorhandler.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 asEMAIL_TOO_LONG,VALUE_TOO_LONGandEMAIL_ALREADY_EXISTS.error_descriptionis 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/brandor/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.
Error codes
Section titled “Error codes”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. |
Saving a whole list
Section titled “Saving a whole list”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.