Error codes
Every machine-readable error code the CID gateway returns, what it means and what to do about it.
- Type: reference
Every machine-readable code a CID gateway error body carries. Clients key behaviour on code,
never on the message text. Regenerate with make docs-generate.
The list comes from the gateway build, so it is exactly the set of codes this release can return.
The wording of a message may change between releases; the code does not, which is why clients
key on it.
Error codes (30)
| Code | HTTP | What it means | What to do |
|---|---|---|---|
CAPABILITY_ACCESS_STALE | 409 | Someone else saved the capability-access table while this screen was open, and this save would overwrite their change. | Reload the access-control page, re-apply your change, and save again. |
CSRF_TOKEN_INVALID | 403 | The request authenticated with the session cookie but carried no matching X-CSRF-Token header. A cookie is sent automatically by the browser, so the header is what proves the request came from the dashboard rather than from another site. | Send the value of the readable cid_csrf cookie as the X-CSRF-Token header on every POST/PUT/PATCH/DELETE. Reload the dashboard if the cookie is missing. Bearer-token callers are unaffected. |
FEATURE_NOT_LICENSED | 403 | The endpoint belongs to a module that the installed licence tier does not include. The response names the feature key and the current tier. | Contact your CID representative to upgrade the tier, then re-install the licence under Settings → License. The feature appears without a restart. |
FINDING_ALREADY_OPEN | 409 | A compliance finding is already open for this detection; only one live finding per detection is permitted. The response names the existing finding. | Open the existing finding instead of creating a second one, or close it first if the intent was to reopen a different one. |
GROUP_MAPPED_BY_SYNC_SCOPE | 409 | The tenant group is the sync target of one or more directory (AD/LDAP) sync scopes, which the response lists. Deleting it would leave those scopes pointing at nothing and break login grouping. | Re-point the listed sync scopes at another group, or clear the mapping, under Settings → LDAP, then delete the group. |
GROUP_NOT_EMPTY | 409 | The tenant group still holds members and/or provider credentials, which the response counts. Deleting it would orphan them. | Remove the members and move the credentials to another group or tenant, then delete the group. |
INVALID_SCOPE | 400 | The 'scope' field of a role assignment was malformed. It must be '{ type: 'tenant' | 'tenant_group', id: <uuid> }'. | Correct the scope object, or omit it entirely — role assignments currently apply system-wide. |
LICENSE_EXPIRED | 402 | The installed CID licence is expired or invalid, so product usage (chat, detection, inspection) is blocked. Administration and licence installation stay reachable. | Install a renewal under Settings → License. Air-gapped boxes take an offline .lic file from your CID representative. |
LIMIT_EXCEEDED | 403 | Creating this account would exceed the account ceiling the licence sets. The response carries the ceiling and the number in use. | Delete or deactivate accounts that are no longer used, or upgrade the licence to a larger seat count. Every refusal is recorded in the event log. |
MFA_ALREADY_ENROLLED | 409 | The account already has an authenticator app enrolled; enrolment is not repeated over a live one. | Use the existing authenticator. To move to a new phone, ask a superadmin to reset two-factor for the account, then enrol again at the next sign-in. |
MFA_CHALLENGE_EXHAUSTED | 401 | Five wrong codes were entered for this sign-in, so the challenge was discarded and no further code is accepted for it. | Sign in again with the password to receive a new challenge. If the codes keep failing, use a recovery code or ask a superadmin to reset two-factor for the account. |
MFA_CHALLENGE_EXPIRED | 410 | The five-minute window for completing the second factor closed before a valid code arrived. | Sign in again with the password; the new challenge starts a fresh five-minute window. |
MFA_CHALLENGE_INVALID | 401 | The challenge token presented does not belong to a live sign-in: it was already completed, replaced by a newer sign-in, or was never issued by this gateway. | Sign in again with the password and complete the second factor in the same browser session, without reusing an older challenge. |
MFA_DISABLE_WOULD_LOCK | 409 | The two-factor policy on this installation applies to this account, so turning the authenticator off would leave the account unable to sign in. | Keep the authenticator. To switch phones, regenerate recovery codes first or ask a superadmin to reset two-factor so the next sign-in enrols the new device. |
MFA_INVALID_CODE | 401 | The authenticator or recovery code did not match. The response may carry attempts_left; every wrong code counts against the same challenge. | Enter the current code from the authenticator app (it changes every 30 seconds and the phone clock must be right), or an unused recovery code. After five failures start the sign-in again. |
MFA_NOT_ENROLLED | 400 | The account has no authenticator app enrolled, so there is nothing to disable and no recovery codes to regenerate. | Enable two-factor from the profile page (or sign in, which enrols when the policy requires it) before using these actions. |
MFA_RATE_LIMITED | 429 | Too many second-factor attempts from this address or for this account in a short time. The limit protects the six-digit code from being guessed. | Wait for the number of seconds in the Retry-After header, then try again with the current code from the authenticator app. |
MFA_REQUIRED | 403 | The account requires two-factor sign-in and the browser extension has no way to enter an authenticator code, so the password alone was refused and no token was issued. | Sign in through the dashboard, which asks for the authenticator code. For the extension, use a gateway API key (cid_key_) instead of a password until the extension supports the code step. |
MFA_SECRET_NOT_PERSISTENT | 503 | JWT_SECRET is not set, so the gateway is running on a per-boot secret and authenticator seeds encrypted under it would become unreadable at the next restart. Enrolment is refused rather than risk locking every account. | Set a persistent JWT_SECRET in the environment (openssl rand -hex 64), restart the gateway, and enrol again. |
PAGE_ACCESS_STALE | 409 | Someone else saved the page-access table while this screen was open. The editor sends the whole table, so saving now would silently overwrite their change. | Reload the access-control page to pick up the other edit, re-apply your change, and save again. |
READ_ONLY_ROLE | 403 | The signed-in account holds the read-only demo role (viewer), which may read every page but may not change anything. The request was a write. | Sign in with an account that has a writing role (admin_user or user), or ask an administrator to change the role of this account under Tenants & users. |
READ_ONLY_ROLE_NO_SIGNED_MATERIAL | 403 | A read-only demo account (viewer) asked the owner console for a signed licence file. Signed material is withheld from demo accounts even on read paths, because the file is usable off the box. | Issue and download licences with a full owner-console account. The refusal is deliberate and is not a licensing fault. |
ROLE_NOT_FOR_CHAT | 403 | The signed-in account holds the auditor role, which reviews the estate rather than adding traffic to it, so it cannot send chat messages or create chat sessions. | Use the dashboard for review work. To send prompts, sign in with a user or admin_user account, or call the gateway with a cid_key_ API key. |
ROLE_NOT_RELEASED | 400 | The role exists in this build but is not assignable yet: its capabilities are not enforced by the API, so an account holding it would be refused everywhere. | Assign a released role for now. The role becomes assignable in the release that ships its endpoint decorators. |
SCOPE_NOT_ENABLED | 400 | A well-formed scope was sent, but scoping a role to a single tenant or tenant group is not enabled in this release. Role assignments apply to the entire system. | Omit scope from the assignment. To limit what an account sees, put it in the tenant group that carries the data instead. |
SESSION_EXPIRED | 401 | The sign-in session behind this token has ended: it was signed out, revoked by an administrator, ended by a password change or a two-factor reset, went unused past the idle window, or reached its maximum lifetime. | Sign in again. If this keeps happening within minutes, check whether an administrator is revoking sessions or whether the account was deactivated. |
SESSION_REFRESH_REUSED | 401 | A refresh token that had already been rotated was presented again. That is the signature of a copied token, so the whole session was ended rather than refreshed. | Sign in again. If nobody else used the account, this usually means a browser restored a stale tab from disk; if it repeats, treat the device as compromised and change the password. |
SESSION_REQUIRED | 401 | The token is validly signed but names no session. Tokens issued before revocable sessions shipped have no session to check, and are refused rather than trusted. | Sign in again to obtain a current token. Scripts holding a long-lived token from an earlier release must repeat their login once after the upgrade. |
SETUP_REQUIRED | 423 | The appliance has not finished first-boot setup, so every route outside the setup wizard is locked. | Open the dashboard and complete the first-boot wizard (administrator account, network, licence). Until then only /setup, /auth and /certs answer. |
UNKNOWN_ROLE | 400 | The role key in the request is not one this build defines. | Send one of the roles listed by the access-control page. Check for a typo or for a role name from a newer build. |