# Error codes

> **Sentinel v2 (beta):** This page documents Sentinel v2, a beta rewrite that may change before the stable release. It does not apply to Sentinel v1, the current stable version: see the [Sentinel v1 documentation](/docs/sentinel.md).

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.

```json
{
"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](#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](/sentinel-api-docs-v2.html). For a body timeout, check the client's upload or raise [`body_read_timeout`](/docs/sentinel/v2/reference/configuration/#connection-timeouts). |
| 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](/docs/sentinel/v2/reference/configuration/#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](/docs/sentinel/v2/reference/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`](/docs/sentinel/v2/reference/cli/); see [Troubleshooting](/docs/sentinel/v2/operations/troubleshooting/). |

A request to a host outside a listener's [`allowed_hosts`](/docs/sentinel/v2/reference/configuration/#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](/docs/sentinel/v2/plans/) and [Licensing](/docs/sentinel/v2/configure/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](/docs/sentinel/v2/features/threat-intelligence/#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](/docs/sentinel/v2/configure/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](/docs/sentinel/v2/security/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](/docs/sentinel/v2/operations/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](/docs/sentinel/v2/concepts/accounts-users/) and [API keys](/docs/sentinel/v2/concepts/api-keys/#restricted-vs-full).

| 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](/docs/sentinel/v2/concepts/api-keys/) and the [Rules reference](/docs/sentinel/v2/reference/rules/).

| 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](/docs/sentinel/v2/policies/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](/docs/sentinel/v2/policies/api-keys/#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](/docs/sentinel/v2/features/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](/docs/sentinel/v2/features/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](/docs/sentinel/v2/reference/rules/). |
| 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](/docs/sentinel/v2/concepts/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](/docs/sentinel/v2/features/threat-intelligence/). |
| 409 | `USERNAME_TAKEN` | `POST /v2/users`, `PATCH /v2/users/{id}` | Another user has this username. | Choose another username. |

## Training data

See [Similarity](/docs/sentinel/v2/features/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

See [Licensing](/docs/sentinel/v2/configure/licensing/) and [Plans](/docs/sentinel/v2/plans/).

| 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](#oauth-redirect-errors)) | 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](/docs/sentinel/v2/operations/clustering/). |
| 503 | `LICENSE_STANDBY` | Every route on the main listener except `GET /`, `/.health` included | This replica is a [standby instance](/docs/sentinel/v2/operations/clustering/#standby-instances) (`[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](/docs/sentinel/v2/operations/snapshots/). `PAYLOAD_TOO_LARGE` is under [General](#general); `STORAGE_ERROR` under [Upstream services](#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`](/docs/sentinel/v2/reference/cli/). |
| 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](/docs/sentinel/v2/configure/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](/docs/sentinel/v2/configure/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](/docs/sentinel/v2/configure/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](/docs/sentinel/v2/operations/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](/docs/sentinel/v2/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](/docs/sentinel/v2/features/threat-intelligence/#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](/docs/sentinel/v2/security/sign-in/) for the OAuth setup.
