Errors are returned as { "error": "…", "code": "…" }.
| Code | HTTP | Meaning |
|---|
invalid_credentials | 401 | Wrong identity or password (never says which) |
bad_identity_type | 400 | identity_type names a column not declared for auth |
unknown_realm | 400 | The realm is missing or inactive |
provider_not_allowed | 403 | The realm doesn’t allow the requested provider |
token_reuse | 401 | A rotated refresh token was replayed — the whole rotation family is revoked |
code_reused | 401 | A TOTP code was reused within its step |
invalid_code | 401 | Wrong TOTP code (e.g. on MFA disable) |
webauthn_disabled | 503 | WebAuthn isn’t configured for this tenant |
| Code | HTTP | Meaning |
|---|
scope_exceeds_authority | 403 | Requested API-key capabilities exceed the issuer’s own |
apikey_required | 401 | No API key presented to the token-exchange endpoint |
apikey_invalid | 401 | The API key is invalid (unknown key and bad secret are indistinguishable) |
not_a_service_key | 403 | The API key carries no service scope and cannot be exchanged |
| Code | HTTP | Meaning |
|---|
invalid_session | 401 | Session invalid, expired, or revoked (reason not disclosed) |
unknown_session | 404 | No session with that control-plane id (rotate) |
| Code | HTTP | Meaning |
|---|
invalid tenant | 400 | The CPET headers match no configured tenant |
engine_unavailable | 500 | The tenant has no resolvable config, or its database is unreachable |
v2.requires_admin | 403 | The route requires an admin role |
v2.requires_superadmin | 403 | The route requires a control-plane (superadmin) token — e.g. applying a migration plan |
rate_limited | 429 | A credential endpoint’s rate limit tripped (Retry-After set) |
For the JWKS/token-verification errors a relying service sees (e.g. “no configured URL for issuer”), see Configuration → Verifying IAM tokens.
