Error codes
This page lists every error code the Sentinel /v2 API returns, the shape of error responses, and the error codes of the OAuth login redirect.
Error response
Every error has the same JSON body. Branch on code, never on error: the message is for humans and may change.
{
"code": "LICENSE_LIMIT_REACHED",
"data": { "limit": "users", "max": 1 },
"error": "Licensed limit of users reached (1).",
"statusCode": 403
}| Field | Type | Description |
|---|---|---|
code | string | Machine-readable cause, e.g. VALIDATION_ERROR. Listed in the tables below. |
data | object | Only on some errors (see Extra data and headers); omitted otherwise. |
error | string | Human-readable message. For VALIDATION_ERROR and some other codes it names the failing field or reason. |
statusCode | number | The HTTP status code, repeated in the body. |
Extra data and headers
| Code | Extra | Description |
|---|---|---|
ACCESS_DENIED | data | Only on GET /v2/inspect: the full inspect result (the same object a successful call returns), including securityRules when [inspect] security_rules is on. Other endpoints return the error fields only. |
ASSISTANT_RATE_LIMITED | retry-after header | Seconds to wait, as sent by the assistant service (60 when it sent none). |
HEADER_ENTROPY | retry-after, x-ratelimit-limit, x-ratelimit-window headers | Same headers as RATE_LIMITED. x-ratelimit-limit is the header-entropy limit; no data. |
LICENSE_LIMIT_REACHED | data | limit (accounts, users, api_keys or security_groups) and max (the licensed number). |
LICENSE_NOT_ACTIVE | data | status: none, expired, refresh_overdue, revoked or not_yet_valid. |
RATE_LIMITED | retry-after, x-ratelimit-limit, x-ratelimit-window headers | retry-after is whole seconds (at least 1); x-ratelimit-limit is the points of the exceeded limit; x-ratelimit-window its window in seconds. No data. |
Refusals on the widget endpoints (/v2/challenge, /v2/challenge/audio/…, /v2/verify, /v2/inspect) carry the CORS headers too, including rate-limit and licensing errors, so a browser page can read them.
General
| HTTP | Code | Endpoint(s) | Meaning | Fix |
|---|---|---|---|---|
| 400 | VALIDATION_ERROR | Any endpoint with a body, path id or query | Malformed or mistyped JSON, wrong Content-Type, a JSON body over the size limit, or a field with a bad length, range, format or id prefix. error names the field. Also a request body that stalled longer than [server] body_read_timeout (error: … request body read timed out). | Correct the field named in error; check the request schema in the API reference. For a body timeout, check the client's upload or raise body_read_timeout. |
| 403 | IP_NOT_ALLOWED | GET /.health | The client IP isn't in [server] health_allowed_ips, or the request carries forwarding headers from a peer outside trusted_proxies. | Probe from an allowed address, add it to health_allowed_ips, or list the proxy in trusted_proxies; see Health endpoint. |
| 404 | NOT_FOUND | Any | Unknown route; a record that doesn't exist, is deleted, or belongs to an account you can't access (existence is hidden); unknown OAuth provider; a route whose feature is off: passkeys without an auth base URL, POST /v2/auth/ldap without [auth.ldap], POST /v2/assistant without [assistant], POST /v2/eml with [eml] enabled = false, /v2/snapshots with [snapshots] enabled = false, GET /v2/inspect with [inspect] enabled = false; GET /v2/challenge/audio/{file} with an invalid or expired token, a token issued to another network, or a token of a challenge issued without audio (codeChallenge.audio set to false, or no codeChallenge.audioLanguages voice that speaks the code). On the [server.public_api] listener, every non-widget path. | Check the id and your membership in its account; enable the feature in the configuration; call management routes on the main or admin listener. |
| 409 | CONFLICT | Create and update endpoints | The write collides with an existing record's unique value, e.g. two concurrent creates. | Re-read the record and retry with a unique value. |
| 413 | PAYLOAD_TOO_LARGE | POST /v2/eml, POST /v2/snapshots/_restore | The body exceeds [eml] max_body_size (default 5000000 bytes) or [snapshots] max_upload_size (default 1073741824 bytes). | Send a smaller body or raise the limit. |
| 500 | INTERNAL_ERROR | Any | Server fault, e.g. the database or log store is unavailable. Details are logged server-side only. | Check the server log and run altcha-sentinel doctor; see Troubleshooting. |
A request to a host outside a listener's allowed_hosts gets 421 Misdirected Request with the plain-text body misdirected request, not the JSON error body.
Sign-in and sessions
| HTTP | Code | Endpoint(s) | Meaning | Fix |
|---|---|---|---|---|
| 400 | INVALID_ALTCHA_PAYLOAD | POST /v2/auth/login, POST /v2/auth/ldap | The login ALTCHA payload isn't valid base64 JSON. | Solve the challenge from GET /v2/auth/challenge and send the widget's payload unchanged. |
| 400 | NO_PASSKEYS | POST /v2/auth/login/passkey/options, POST /v2/me/verify/passkey/options | The user has no passkey. | Use TOTP, or register a passkey first. |
| 401 | INCORRECT_OTP | POST /v2/auth/login/otp | Wrong TOTP code. Counts toward the otpJwt's 5 attempts. | Enter the current code; check the device clock. |
| 401 | INVALID_CREDENTIALS | POST /v2/auth/login, POST /v2/auth/ldap | Unknown user or wrong password. | Check the username and password. |
| 401 | INVALID_OTP_TOKEN | POST /v2/auth/login/otp, POST /v2/auth/login/passkey, POST /v2/auth/login/passkey/options | The otpJwt from the password step is missing, invalid or expired. | Log in again to get a fresh otpJwt. |
| 401 | INVALID_PASSKEY_CHALLENGE | POST /v2/auth/login/passkey | The passkey challengeJwt is invalid, expired (5 minutes) or already used. | Request new options and retry. |
| 401 | OTP_ATTEMPTS_EXCEEDED | POST /v2/auth/login/otp, POST /v2/auth/login/passkey, POST /v2/auth/login/passkey/options | 5 failed second-factor attempts (codes and passkeys together) locked the otpJwt. | Log in again with the password. |
| 401 | PASSKEY_VERIFICATION_FAILED | POST /v2/auth/login/passkey | The passkey assertion didn't verify. | Retry with a passkey registered for this user and this auth base URL. |
| 401 | UNAUTHORIZED | Every session endpoint | Missing, invalid, expired or revoked session token, or an API key sent to an endpoint that accepts only a session (everything except the account-management endpoints a full key may call). | Log in again; send the session as the jwt cookie or a Bearer token. |
| 403 | ALTCHA_VERIFICATION_FAILED | POST /v2/auth/login, POST /v2/auth/ldap | The login ALTCHA solution is wrong, expired or already used. | Solve a fresh challenge. |
| 403 | FEATURE_NOT_LICENSED | POST /v2/auth/ldap | The license lacks the ldap feature. | Get a license with ldap; see Plans and Licensing. |
| 403 | IP_BLOCKED | POST /v2/auth/login, POST /v2/auth/ldap, POST /v2/auth/login/otp, POST /v2/auth/login/passkey/options, POST /v2/auth/login/passkey | A threat entry (manual or auto, not a source list) blocks the client IP and [auth] block_threats is on. Checked before the ALTCHA and the credentials. Doesn't count as a threat signal. | Log in from another IP, or have a root user set the entry's action to allow or delete it; see Blocking logins. |
| 403 | LDAP_NOT_ALLOWED | POST /v2/auth/ldap | The user isn't in any [auth.ldap] allowed_groups group. | Add the user to an allowed group, or adjust allowed_groups. |
| 403 | LICENSE_LIMIT_REACHED | POST /v2/auth/ldap | First login would create a user over the license's users limit. | Delete unused users or raise the limit; see Licensing. |
| 403 | PASSWORD_LOGIN_DISABLED | POST /v2/auth/login | [auth] password_login = false with a licensed OAuth provider or LDAP configured. | Sign in with OAuth or LDAP; see Sign-in. |
| 403 | USER_DISABLED | POST /v2/auth/login, POST /v2/auth/ldap | The user is deactivated or deleted. | A root user reactivates the user with PATCH /v2/users/{id}. |
| 502 | LDAP_FAILED | POST /v2/auth/ldap | The LDAP server is unreachable, TLS failed, the service account was refused, or a search failed. | Check [auth.ldap] URL, TLS settings and service-account credentials; see the server log. |
Account self-service
Endpoints under /v2/me for the signed-in user: second factors, password, and push subscriptions.
| HTTP | Code | Endpoint(s) | Meaning | Fix |
|---|---|---|---|---|
| 400 | INCORRECT_OTP | POST /v2/me/otp, POST /v2/me/verify | Wrong TOTP code. On POST /v2/me/verify it counts toward the step-up limit. | Enter the current code; check the device clock. |
| 400 | INCORRECT_PASSWORD | POST /v2/me/password | The current password is wrong. | Send the current password. |
| 400 | INVALID_OTP_SECRET | POST /v2/me/otp | The TOTP secret isn't the one issued by GET /v2/me/otp. | Start setup again with GET /v2/me/otp. |
| 400 | INVALID_PASSKEY_CHALLENGE | POST /v2/me/passkeys, POST /v2/me/verify | The passkey challengeJwt is invalid, expired (5 minutes) or already used. | Request new options and retry. |
| 400 | INVALID_PUSH_SUBSCRIPTION | POST /v2/me/push-subscriptions | Not an https:// endpoint on an [alerts.push] endpoint_hosts host (or subdomain), longer than 2048 characters, or malformed keys. | Subscribe from a supported browser, or add the push service host to endpoint_hosts. |
| 400 | OTP_NOT_ENABLED | POST /v2/me/verify | A TOTP code was sent, but the user has no TOTP. | Verify with a passkey instead. |
| 400 | PASSKEY_VERIFICATION_FAILED | POST /v2/me/passkeys, POST /v2/me/verify | The passkey registration or assertion didn't verify. | Retry; the auth base URL host must match the page's origin. |
| 400 | PUSH_NOT_CONFIGURED | POST /v2/me/push-subscriptions, POST /v2/me/push-subscriptions/{id}/_test | Web push is off: no [alerts.push] section. | Set [alerts.push] subject and [secrets] vapid_private_key; see Alerts. |
| 403 | PASSWORD_LOGIN_DISABLED | POST /v2/me/password | [auth] password_login = false. | Change the password at the identity provider. |
| 403 | PASSWORD_NOT_SET | POST /v2/me/password | The user has no password (an OAuth or LDAP user). | Manage the password at the identity provider. |
| 403 | STEP_UP_REQUIRED | POST /v2/me/otp, POST /v2/me/passkeys, DELETE /v2/me/passkeys/{id} | The user has a second factor and sent no valid x-step-up-token. | Call POST /v2/me/verify and send its token in x-step-up-token. |
| 409 | LAST_SECOND_FACTOR | DELETE /v2/me/passkeys/{id} | This is the user's only passkey and TOTP is off. | Enable TOTP or add another passkey first. |
| 409 | OTP_ALREADY_ENABLED | GET /v2/me/otp, POST /v2/me/otp | TOTP is already on. | A root user resets it with POST /v2/users/{id}/_disable_otp. |
| 409 | PASSKEY_ALREADY_REGISTERED | POST /v2/me/passkeys | This credential is already registered. | Use another authenticator. |
| 409 | TOO_MANY_PASSKEYS | POST /v2/me/passkeys/options, POST /v2/me/passkeys | The user has 20 passkeys. | Delete one first. |
| 409 | TOO_MANY_PUSH_SUBSCRIPTIONS | POST /v2/me/push-subscriptions | The user has 20 subscriptions. | Delete one first. |
| 410 | PUSH_SUBSCRIPTION_EXPIRED | POST /v2/me/push-subscriptions/{id}/_test | The push service no longer accepts the subscription; Sentinel deleted it. | Subscribe again from the browser. |
| 429 | STEP_UP_ATTEMPTS_EXCEEDED | POST /v2/me/verify | 5 failed verifications in 10 minutes. | Wait and retry. |
| 502 | PUSH_FAILED | POST /v2/me/push-subscriptions/{id}/_test | The push service failed. | Retry later; check outbound access to the push service. |
Permissions
Session endpoints, and full API keys on the account-management endpoints, check the caller's role in the account the request targets. A full key uses its security group's role. See Accounts & users and API keys.
| HTTP | Code | Endpoint(s) | Meaning | Fix |
|---|---|---|---|---|
| 403 | PERMISSION_REQUIRED | Session and full-key endpoints with accountId or filter.accountId; POST /v2/assistant | The caller's role has no access to the feature in that account. For a full key: its security group has no role, the role doesn't list the feature, or the request targets another account. | Grant the feature in the role, add a membership to the account, or have root set the group's role. |
| 403 | READ_ONLY_ROLE | Write endpoints for sessions and full keys | The caller's role is read-only. | Use a role without readonly. |
| 403 | ROOT_PRIVILEGES_REQUIRED | Root-only endpoints: accounts, roles, users, system-wide alerts, remote files, cluster, doctor, snapshots, license. Also setting a security group's role, and creating, changing or deleting a group that has a role or its API keys | The caller isn't a root user (full API keys never are). | Sign in as a root user. |
API keys and security rules
Codes of endpoints authenticated with an API key (widget, classification, lookups, and account management with a full key) and of the security group's rules. See API keys and the Rules reference.
| HTTP | Code | Endpoint(s) | Meaning | Fix |
|---|---|---|---|---|
| 400 | INVALID_PAYLOAD | POST /v2/verify | The ALTCHA payload can't be decoded. Other verification failures return 200 with verified: false. | Send the widget's payload unchanged. |
| 401 | API_KEY_REQUIRED | Every API-key endpoint | No key, an unsupported scheme, malformed Basic credentials, or a wrong secret. On endpoints that need Basic credentials, a session token counts as no key. | Send the key: public keys by id, restricted/full keys with Basic id:secret. |
| 403 | ACCESS_DENIED | Every API-key endpoint | A security-group rule denied the request. error is the rule's message, or Denied by access rules (rule N). | Review the group's rules; see Security rules. |
| 403 | ACCOUNT_DELETED | Every API-key endpoint | The key's account is deleted. | Create a key in an active account. |
| 403 | ACCOUNT_SUSPENDED | Every API-key endpoint | The key's account is inactive. | A root user reactivates the account. |
| 403 | API_KEY_EXPIRED | Every API-key endpoint | The key's expiresAt has passed. | Switch the client to another key, or give the key a later expiresAt or null; see Set an expiry. |
| 403 | API_KEY_INVALIDATED | Every API-key endpoint | The key or its security group is deleted. | Create a new key. |
| 403 | API_KEY_NOT_FOUND | Every API-key endpoint | Unknown or malformed key id. On widget endpoints and GET /v2/inspect, a session token sent as a Bearer token is looked up as a key id and gets this code. | Check the key id; send a key, not a session token. |
| 403 | BASIC_AUTH_NON_PUBLIC_API_KEY | Every API-key endpoint | A public key sent with Basic credentials. | Send a public key by id (Bearer or apiKey query), without a secret. |
| 403 | BEARER_AUTH_PUBLIC_API_KEY | Every API-key endpoint | A restricted or full key sent by id (Bearer or query). | Send it with Basic id:secret. |
| 403 | FULL_API_KEY_REQUIRED | Account-management endpoints: /v2/security-groups*, /v2/api-keys*, /v2/request-logs*, POST /v2/alerts/_search, /v2/training-data* (except _feedback), /v2/training-suggestions* | A public or restricted key called a management endpoint. | Use an admin session, or a full key whose security group has a role. |
| 403 | HIS_BLOCKED | POST /v2/challenge | his.mode relaxed or strict blocked the client. The reason is never revealed. | Tune his.mode and his.blockThreshold; see Human Interaction Signature. |
| 403 | NON_PUBLIC_API_KEY_REQUIRED | POST /v2/classifier, POST /v2/eml, POST /v2/ip, POST /v2/language, POST /v2/phishing, POST /v2/similarity, POST /v2/threat, POST /v2/threat/_report, POST /v2/time-zone, POST /v2/training-data/_feedback, POST /v2/user-agent, POST /v2/verify/signature | A public key called a backend endpoint. | Use a restricted or full key from your server. |
| 403 | PUBLIC_API_KEY_REQUIRED | GET /v2/challenge, POST /v2/challenge, GET /v2/challenge/audio/{file}, POST /v2/verify | A restricted or full key called a widget endpoint. | Give the widget a public key. |
| 429 | HEADER_ENTROPY | GET /v2/challenge (HIS off), POST /v2/challenge, GET /v2/inspect | The client IP sent more distinct header sets than headerEntropy.limit allows. | Wait retry-after seconds; raise headerEntropy.limit if real users hit it. |
| 429 | RATE_LIMITED | Every /v2 request and, with [server] v1_compat, every /v1 widget alias ([rate_limit] global, per client IP); API-key requests (rateLimit.limits of the security group); GET /v2/challenge/audio/{file} ([code_challenge] audio_rate_limit, default 10/5m) | A rate limit is exceeded. | Wait retry-after seconds. If legitimate traffic is limited, raise the limit or set [server] trusted_proxies / client_ip_header so clients aren't seen as one IP; see Rate limiting. |
Management API
Endpoints that manage accounts, roles, users, security groups, API keys and threat intelligence. Most accept only a session; the account-scoped ones also accept a full API key whose security group has a role.
| HTTP | Code | Endpoint(s) | Meaning | Fix |
|---|---|---|---|---|
| 400 | ACCOUNT_NOT_FOUND | POST /v2/users, PATCH /v2/users/{id} (accounts[].accountId); POST /v2/security-groups; training-data and training-suggestion endpoints; POST /v2/assistant | The accountId names no account, or a deleted one. | Use the id of an active account. |
| 400 | CANNOT_MODIFY_SELF | PATCH /v2/users/{id}, DELETE /v2/users/{id} | A root user tried to deactivate, demote or delete themselves. | Have another root user make the change. |
| 400 | INVALID_RULES | POST /v2/security-groups, PATCH /v2/security-groups/{id} | The group's rules don't compile: unknown field, operator, signal or value, or a value out of range. error says which. | Fix the rule error names; see the Rules reference. |
| 400 | ROLE_NOT_FOUND | POST /v2/users, PATCH /v2/users/{id} (accounts[].role); POST /v2/security-groups, PATCH /v2/security-groups/{id} (role) | The role doesn't exist or is deleted. | Use an existing role id. |
| 400 | SECURITY_GROUP_NOT_FOUND | POST /v2/api-keys, PATCH /v2/api-keys/{id} | The security group doesn't exist, or the caller has no access to it. | Use a group of the key's account that you can access. |
| 400 | UNKNOWN_FEATURE | POST /v2/roles, PATCH /v2/roles/{id} | permissions contains an unknown feature name. | Use only listed feature names; see Accounts & users. |
| 409 | ROLE_IN_USE | DELETE /v2/roles/{id} | A membership or a non-deleted security group uses the role, including memberships of deleted users and accounts. | Move those memberships to another role and clear the groups' role, or deactivate the role instead. |
| 409 | ROLE_NAME_TAKEN | POST /v2/roles, PATCH /v2/roles/{id} | Another role (deleted ones included) has this name. | Choose another name. |
| 409 | SECURITY_GROUP_IN_USE | DELETE /v2/security-groups/{id} | API keys still use the group. | Move or delete those keys first. |
| 409 | THREAT_ENTRY_EXISTS | POST /v2/threat-entries | An entry (manual or automatic) for the same canonical IP exists. | Update the existing entry with PATCH /v2/threat-entries/{id}. |
| 409 | THREAT_SOURCE_NAME_TAKEN | POST /v2/threat-sources, PATCH /v2/threat-sources/{id} | Another source (deleted ones included) has this name. | Choose another name; see Threat intelligence. |
| 409 | USERNAME_TAKEN | POST /v2/users, PATCH /v2/users/{id} | Another user has this username. | Choose another username. |
Training data
See Similarity.
| HTTP | Code | Endpoint(s) | Meaning | Fix |
|---|---|---|---|---|
| 400 | EMBEDDINGS_DISABLED | POST /v2/training-data/_evaluate | No embedding model: [similarity] provider = "none". | Set [similarity] provider to local or openai. |
| 400 | INSUFFICIENT_SAMPLES | POST /v2/training-data/_evaluate | The group has fewer than 3 embedded positive samples, or doesn't exist. | Add positive samples to the group. |
| 400 | TRAINING_DATA_LIMIT | POST /v2/training-data, POST /v2/training-data/_import, POST /v2/training-data/_feedback, POST /v2/training-suggestions/{id}/_accept | The account would exceed [similarity] max_samples_per_account (default 10000). An import then stores nothing. | Delete samples or raise the limit. |
| 409 | LABEL_CONFLICT | POST /v2/training-data/_feedback, POST /v2/training-suggestions/{id}/_accept | The group has a near-duplicate with the opposite label. error names it. | Decide which label is right, then fix or delete the conflicting sample. |
Licensing
| HTTP | Code | Endpoint(s) | Meaning | Fix |
|---|---|---|---|---|
| 403 | BACKEND_NOT_LICENSED | Every /v2 route except /v2/auth/*, /v2/me*, /v2/app-config, /v2/license*, /v2/doctor* | The embedded database or KV backend isn't licensed (exotdb.backend.<kind>). | Get a license that includes the backend, or switch [database] / [redis] to a licensed backend. |
| 403 | FEATURE_NOT_LICENSED | POST /v2/auth/ldap; OAuth login (as a redirect error) | The license lacks the ldap or oauth feature. | Get a license with the feature. |
| 403 | LICENSE_LIMIT_REACHED | POST /v2/accounts, POST /v2/api-keys, POST /v2/security-groups, POST /v2/users, first LDAP or OAuth login | Creating the record would exceed the license's accounts, api_keys, security_groups or users limit. data names it. | Delete unused records (deleted ones don't count) or raise the limit. |
| 403 | LICENSE_NOT_ACTIVE | Widget routes (/v2/challenge, /v2/challenge/audio/{file}, /v2/verify, /v2/inspect) and feature routes (/v2/classifier, /v2/eml, /v2/ip, /v2/language, /v2/phishing, /v2/similarity, /v2/threat, /v2/threat/_report, /v2/time-zone, /v2/user-agent, /v2/verify/signature) | No active license. data.status says why. | Install or renew the license in [license]. |
| 503 | LICENSE_INSTANCE_LIMIT | Same routes as BACKEND_NOT_LICENSED | This replica holds no instance slot: the license's instances limit is reached. | Stop surplus replicas or raise the limit; see Clustering. |
| 503 | LICENSE_STANDBY | Every route on the main listener except GET /, /.health included | This replica is a standby instance ([license] standby = true) still waiting for a free regular slot. | Expected while production replicas hold every slot. Route traffic to active replicas; the standby starts serving once it takes a slot. |
| 503 | LICENSE_STATE_UNAVAILABLE | GET /v2/license/request | The license state isn't loaded yet, or its store failed. | Retry after startup completes; check the database connection. |
Snapshots
Root-only /v2/snapshots routes. See Snapshots. PAYLOAD_TOO_LARGE is under General; STORAGE_ERROR under Upstream services.
| HTTP | Code | Endpoint(s) | Meaning | Fix |
|---|---|---|---|---|
| 400 | INVALID_SNAPSHOT | POST /v2/snapshots/_restore, POST /v2/snapshots/{name}/_restore | Empty or unreadable upload; not an age file or ZIP; a snapshot of the previous Sentinel version; not a valid export archive; contains a license table or a table that isn't Sentinel's under the current [database] table_prefix. | Restore a snapshot made by this version; convert older ones with altcha-sentinel migrate. |
| 400 | SNAPSHOT_DECRYPT_FAILED | Restore endpoints | [snapshots] identity isn't one of the snapshot's recipients. | Set the identity the snapshot was encrypted for. |
| 400 | SNAPSHOT_KEY_REQUIRED | Restore endpoints | The snapshot is encrypted and [snapshots] identity isn't set. | Set [snapshots] identity. |
| 400 | SNAPSHOT_MISMATCH | Restore endpoints | The archive doesn't fit the current schema, e.g. it has columns the schema lacks. | Restore it on the Sentinel version that made it. |
| 400 | SNAPSHOT_STORAGE_DISABLED | GET /v2/snapshots, POST /v2/snapshots/{name}/_restore | Stored snapshots need a [storage] provider and [snapshots] identity. | Configure both; see Storage. |
| 409 | SNAPSHOT_IN_PROGRESS | POST /v2/snapshots, restore endpoints | Another snapshot or restore is running on any replica. | Wait for it to finish. |
| 502 | DATABASE_TRANSFER_REFUSED | POST /v2/snapshots, restore endpoints | A remote ExotDB server refused the export or import. | Enable [export_import] on the ExotDB server and set [database] token to an admin token. |
Upstream services
Errors caused by a service Sentinel calls. They don't count as threat signals against the client IP.
| HTTP | Code | Endpoint(s) | Meaning | Fix |
|---|---|---|---|---|
| 400 | ASSISTANT_INVALID_REQUEST | POST /v2/assistant | The assistant service rejected the request. error has its message. | Fix the request as error describes. |
| 429 | ASSISTANT_RATE_LIMITED | POST /v2/assistant | The assistant service is busy. | Wait retry-after seconds. |
| 502 | ASSISTANT_UNAVAILABLE | POST /v2/assistant | The assistant service is unreachable, unavailable, failed, or rejected this server's credentials. | Check [assistant] url, key_id and hmac_key, outbound access and the system clock. |
| 502 | CHECK_FAILED | POST /v2/remote-files/{name}/_check | The update check failed: network error, timeout, or a 4xx/5xx status. error has the reason. | Check the file's URL and outbound access; see Remote files. |
| 502 | STORAGE_ERROR | POST /v2/eml (X-Attachments-Upload), snapshot endpoints | A request to the [storage] provider failed. Details are in the server log. | Check the [storage] provider credentials, bucket or container, and [storage] timeout; see Storage. |
| 503 | BROADCAST_FAILED | POST /v2/remote-files/{name}/_update, POST /v2/threat-sources/{id}/_update | The update couldn't be published to the other replicas; no download started. | Check the KV store ([redis]) connectivity and retry; see Clustering. |
OAuth redirect errors
GET /v2/auth/oauth/{provider} and its callback don't return JSON errors (except 404 NOT_FOUND for an unconfigured provider and 400 VALIDATION_ERROR for a redirectUrl outside the auth base URL). Failures redirect to redirectUrl with its fragment replaced by /login?error=CODE; a missing or invalid state cookie redirects to the auth base URL with #/login?error=OAUTH_INVALID_STATE.
| Code | Meaning | Fix |
|---|---|---|
FEATURE_NOT_LICENSED | The license lacks the oauth feature. | Get a license with oauth; see Plans. |
INTERNAL_ERROR | Server fault; details are logged server-side only. | Check the server log. |
IP_BLOCKED | A threat entry blocks the client IP ([auth] block_threats). The start route redirects without contacting the provider. | See Blocking logins. |
LICENSE_LIMIT_REACHED | First login would create a user over the license's users limit. | Delete unused users or raise the limit. |
OAUTH_FAILED | Provider discovery, code exchange or id_token validation failed, or the user cancelled at the provider. | Check the [auth.oauth.<provider>] client id, secret and issuer, and that {base_url}/v2/auth/oauth/{provider}/callback is registered at the provider. |
OAUTH_INVALID_STATE | The state cookie is missing, expired (10 minutes), tampered with or already used, or state doesn't match it. | Start the login again from the same browser. |
OAUTH_NOT_ALLOWED | Google: the account isn't in the configured hosted_domain. | Sign in with an account of the allowed domain. |
USER_DISABLED | The user is deactivated or deleted. | A root user reactivates the user. |
See Sign-in for the OAuth setup.