Error Reference Index

This section provides a comprehensive reference for all error responses returned by the AnkaSecure API. Each error includes a unique URI, HTTP status code, and detailed resolution guidance.

This reference covers API errors returned to a caller: every problem+json body whose type member is a https://docs.ankatech.co/errors/<slug> URI. It does not cover deployment and operational failures — script exit codes, bootstrap and environment-creation faults, container startup problems, and errors raised by Docker Swarm, PostgreSQL, Redis, OpenSearch, TLS or the edge NGINX. Those live in the Error Catalog^*, which is the operational companion to this page. The two do not overlap: no exit code is documented here, and no type URI is documented there.

Many pages below send you to the Developer Hub for the schema and an executable example of the operation that failed. If that surface is new to you, The Developer Hub explains what it is, how to get access, and which of the platform's documentation surfaces answers which kind of question.

Quick Reference Table

This table is complete: every published error page appears in it exactly once, with the status its own page declares. The only pages deliberately absent are the three that are not a single type URI — Unknown Error Type, S2S Relay Envelope and Federated Login Errors — which the navigation groups under Cross-Cutting Surfaces for that reason. The per-status sections further down are a curated reading order, not an inventory; use this table to look a type up.

Error Response Format

All API errors follow the RFC 9457 Problem Details standard and are returned with Content-Type: application/problem+json. RFC 9457 obsoleted RFC 7807 in July 2023; the application/problem+json media type and the five defined members are unchanged, so a client written against RFC 7807 needs no change. The body is a flat JSON object — there is no nested error envelope:

{
  "type": "https://docs.ankatech.co/errors/error-type",
  "title": "Human-readable error title",
  "status": 422,
  "detail": "Additional context about the error",
  "instance": "/api/v3/migration/convert-pkcs7-to-jose",
  "correlationId": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": 1730000000
}

The core fields are defined by RFC 9457:

• type - URI identifying the error category (links to the matching page in this reference)
• title - Short, human-readable summary of the error type
• status - HTTP status code, repeated in the body for convenience
• detail - Human-readable explanation specific to this occurrence
• instance - The request path that produced the error

Two platform extensions accompany the standard fields:

• correlationId - Request correlation identifier, for correlation with server-side logs
• timestamp - Epoch-seconds timestamp of when the error was produced

Some errors add further extensions (for example, PKCS#7 conversion errors include an errorCode, and a missing-key refusal lists every unresolved signer and recipient; OAuth 2.0 errors mirror the RFC 6749 error/error_description fields). See the individual error pages for details.

OAuth 2.0 token-endpoint errors (invalid_request, invalid_client, invalid_grant, unsupported_grant_type and invalid_scope), and the invalid_session of the console sign-in endpoint, use an underscore type suffix so the RFC 9457 type matches the OAuth 2.0 error code exactly.

Where extension members live depends on which service answered

RFC 9457 — and RFC 7807 before it — define extension members as top-level members of the problem object. This platform does not place them uniformly, so a client must know which service produced the body before it reads a non-RFC member. Reading the wrong one returns undefined, and that is the single most common cause of a client falling back to parsing detail.

What is uniform: the five RFC-defined members — type, title, status, detail, instance — are top-level in every service, exactly as the specification requires, and timestamp is top-level everywhere it is emitted, even though by the RFC's definition it too is an extension member.

What moves is the correlation identifier:

The License Server serves no client directly: its refusals reach a client relayed by the Admin API, whose body carries extensions.requestId.

The X-Correlation-Id and X-Request-Id response headers are set by every service, so a client that does not want to branch on the service can correlate from the headers alone.

Core API / PQC Handshake API shape — correlationId is a first-class top-level member (this is the canonical example at the top of this page). extensions carries only the additional per-error members, such as the PKCS#7 conversion errorCode:

{
  "type": "https://docs.ankatech.co/errors/unsupported-pkcs7-format",
  "title": "Unsupported PKCS#7 Format",
  "status": 422,
  "detail": "The requested target format is not compatible with the parsed structure.",
  "instance": "/api/v3/migration/convert-pkcs7-to-jose",
  "correlationId": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": 1751500800,
  "extensions": {
    "errorCode": "INCOMPATIBLE_TARGET_FORMAT"
  }
}

Admin API / Audit API shape — there is no top-level correlationId. The correlation identity is extensions.requestId, so a client must read response.extensions.requestId, not response.requestId. Every other extension member on these two services is likewise nested:

{
  "type": "https://docs.ankatech.co/errors/invalid-input",
  "title": "Invalid Input",
  "status": 400,
  "detail": "Field 'algorithm' is required and must be one of the catalog values.",
  "instance": "/api/v3/admin/tenants/2f1c9d84-6b2e-4d3a-9f57-0a1b2c3d4e5f/keys",
  "timestamp": 1751500800,
  "extensions": {
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

extensions is absent when an error carries none, so read it defensively on every service. Two bodies are produced by a different mapper and carry no extensions and no timestamp at all — the 502 Upstream Service Unavailable and the 504 Upstream Service Timeout.

Dispatch on type — not on errorCode, and never on detail

type is the primary identifier of a problem. RFC 9457 §3.1.1 defines it that way, every distinct condition in this platform has its own dedicated slug, and — decisively — type is the only discriminator that survives every path a response can take to you.

Some Core API and PQC Handshake API bodies additionally carry extensions.errorCode, a stable machine-readable string. It is convenient for a direct integration, but it is not a substitute for type, because it is dropped when the Admin API relays a Core API refusal: the relay's problem view is a closed four-member record — type, title, status, detail — so no extension member of the originating service crosses that boundary. A consumer keyed on errorCode therefore works against the Core API directly and silently stops discriminating on the relayed path.

type crosses it unchanged. So:

• Branch on type. It is stable, it is documented on the page each type URI names, and it is identical on the direct and the relayed path.
• Use errorCode only as a refinement, when it is present, and only where two conditions genuinely share one type. Never as the primary key, and never assume it is present.
• Never parse detail. It is prose written for a human, it is localized, and it is the one member whose exact wording carries no compatibility promise. If you find yourself matching on its text, the discriminator you actually need is a type — please report it so a dedicated one can be published.

// Correct: the type URI is the contract.
switch (problemDetails.getType().toString()) {
    case "https://docs.ankatech.co/errors/key-ops-narrowing-forbidden": widenKeyOpsAndResubmit(); break;
    case "https://docs.ankatech.co/errors/purpose-required":            declarePurposeAndResubmit(); break;
    default:                                                            logAndSurface(problemDetails);
}

detail is a sentence, never a document

detail is always a single human-readable sentence. It is never a nested JSON document, and it is never an error body from another service folded into a string. This holds even when the rejection was detected by an internal service that the one you called forwarded your request to — see S2S Relay Envelope for exactly which members come from where in that case. Where a rejection carries per-item detail, that detail is published as a named extension member (for example extensions.failedEntries), not as text inside detail.

406 Not Acceptable carries no body

Content negotiation is the one deliberate exception to "every error is a problem document". When your Accept header excludes every media type an endpoint can produce, the response is a bare 406 Not Acceptable: status line only, Content-Length: 0, and no Content-Type header.

There is no type slug for it, and it is absent from the table above by design. RFC 9110 §15.5.7 explicitly permits a 406 with no representation, and an empty body is the only response that is representable under every Accept value — including the value that caused the condition. Sending a application/problem+json body to a client that has just declared it cannot accept that type would be self-contradictory.

Practically, for a strict JSON client:

• Accept: application/json on an error-only endpoint returns the endpoint's normal status, not a 406.
• Accept: application/xml (or any value the endpoint cannot satisfy) returns the empty 406.
• A malformed Accept value also returns the empty 406, not a 400: an unparseable header makes the mapping fail to match on its producible types, which is the same condition as an unsatisfiable one.
• */* and an absent Accept header behave exactly as before.

Treat a 406 as a client-side content-negotiation bug: correct the Accept header and retry. Do not attempt to parse the response.

The Browser-Redirect Error Surface

Three external identity-federation legs are top-level browser navigations, not API calls. When one of them fails, the browser is redirected to the console login screen carrying ?error=<code>&ref=<uuid> — there is no response body, and therefore no type, no detail and no correlationId (the correlation identifier is ref). See Federated Login Errors for the seven codes and their remedies.

This is a second error representation, not an exception to the RFC 9457 guarantee above. A surface may use it if and only if all three of the following hold:

1. the request is a top-level browser navigation that the browser renders as a document;
2. the caller therefore cannot read a response body, so an interposing CDN or proxy may replace it;
3. an equivalent typed RFC 9457 refusal remains available on a non-navigation surface for programmatic consumers.

Every non-navigation surface — fetch/XHR, the SDKs, the CLIs and service-to-service calls — returns RFC 9457 Problem Details unconditionally. No error type documented on the pages below is retired, renumbered or made unavailable to a programmatic caller by the redirect projection.

Client Errors (4xx)

Client errors indicate that the request contains incorrect syntax or cannot be fulfilled due to client-side issues.

400 Bad Request

• Invalid Input - Request contains syntactically invalid data or malformed JSON
• Credential Required for Endpoint Change - An update moved the endpoint of a destination holding a sealed credential without supplying a credential for the new endpoint; extensions.field names the credential member, and nothing was written
• Algorithm Not Admitted - The tenant's algorithm policy does not admit the algorithm of a key create, rotation or import; extensions.algorithm and extensions.refusedBy name the algorithm and the refusing check
• Invalid Date Range - A usage-telemetry or usage-export date range is wider than its grain's maximum span
• Invalid PKCS#7 Structure - Provided file is not a valid PKCS#7/CMS structure
• Invalid Request Parameters - The query string or form body could not be decoded (for example an invalid % encoding)
• Missing Request Part - Required multipart form data or request parameters are missing
• Multipart Parts Out Of Order - The payload part arrived before the small part describing it, and a streaming endpoint cannot rewind
• Validation Error - Request passed JSON parsing but failed field validation rules
• Unsupported Keystore Format - Uploaded keystore is in a format the platform does not support
• Keystore Derivation Budget Exceeded - A keystore declares more password-based key derivations than one import may run; split it
• Keystore Secret-Key Entry - A keystore holds a secret-key entry, which an import never keeps
• Keystore Private Key Without Certificate Chain - A keystore holds a private-key entry with no certificate chain
• Key Operation Incompatible - Re-encrypt or re-sign named a symmetric key and an asymmetric (SIMPLE or composite) key
• Key-Protection Declaration Not Valid For This Driver - A key-protection declaration in the driver form was refused by the declared driver's descriptor; extensions name the member, the field and the reason, never a value, and nothing was written or contacted
• Invalid Operation Name - Supplied operation name is not a recognized cryptographic operation
• Signature Mismatch - An audit record tamper-evidence signature did not verify
• Query Range Exceeded - Audit query time range or result window exceeds the maximum allowed
• Rotation Interval Below The Deployment Floor - A rotation-schedule interval is shorter than the shortest interval the deployment admits (P1D unless a development deployment lowers it); extensions.floor states it and nothing was stored
• Observability Signal Not Permitted - A tenant observability destination subscribed to LOGS, which only platform backends export; nothing was saved
• Invalid Request - OAuth 2.0: OAuth 2.0 token request is malformed or missing a required parameter
• Invalid Grant - OAuth 2.0: OAuth 2.0 authorization grant or refresh token is invalid, expired, or revoked
• Unsupported Grant Type - OAuth 2.0: OAuth 2.0 grant type is not supported by the authorization server
• Invalid Scope - OAuth 2.0: OAuth 2.0 requested scope is unknown, malformed, or exceeds the permitted scope
• Administrator Credential Not Admitted - A tenant provisioning carried adminPassword or requirePasswordChange from a caller that may not choose the first administrator's credential; only a platform workload on a development deployment may, extensions.member names the member, and nothing is created
• Invalid DPoP Proof - OAuth 2.0 (RFC 9449): an administrative workload's DPoP proof is missing, repeated, malformed, stale, already used or does not bind the request; 400 at the token endpoint, 401 with WWW-Authenticate: DPoP error="invalid_dpop_proof" at the Admin API
• Instance Claim Code Invalid - The claim code entered on the console's claim screen does not redeem (none minted, wrong, replaced, expired, invalidated, the redeemed code with another address, or any code once the instance is claimed); one body for every case, nothing created
• Invalid Session - OAuth 2.0: the auth_session of a console sign-in step is unknown, already answered or expired; start the sign-in again
• Passkey Registration Refused - A passkey registration response did not verify (origin, RP ID, challenge, user verification or a credential already registered); nothing is stored
• Password Policy Violation - A chosen password breaks the password policy; extensions.rule names the rule

401 Unauthorized

• Unauthorized - Missing or invalid authentication credentials
• Invalid Client - OAuth 2.0: OAuth 2.0 client authentication failed
• Reauthentication Required - The operation requires a recent proof of the person's identity and the token's last authentication is older than the reauthentication window; the session is valid, reauthenticate and retry (RFC 9470)

402 Payment Required

• Deployment License Expired - The deployment's license has lapsed and it has entered cryptographic read-only mode; operations that create new protection or new key material are refused, while decrypt, verify and reads continue
• Payment Required - A usage or plan-limit refusal. Deployment-license expiry is a different problem with a different type — see the entry above

403 Forbidden

• Deployment Policy Is Compliance-Immutable - The deployment was created for a regulated compliance region, so its deployment policies are locked for the lifetime of the deployment; not an authorization refusal, and no scope admits the write
• Forbidden - Authenticated but lacking permission for the requested operation
• Key Below Security-Strength Floor - An encryption or signature named a key whose security strength is below the tenant's minimum; extensions.securityStrengthBits and extensions.minSecurityStrengthBits name both. Decrypting, verifying and moving data off the key stay admitted
• SaaS-Only Feature - Feature is available only in the ANKASecure SaaS deployment
• Unsupported Principal Type - Authenticated principal type is not supported for the operation
• Scope Subset Rule Violation - The request would confer on somebody else an authority the caller does not itself hold
• Operation Not Available While Impersonating - The route is withheld from a support-access impersonation session
• Break-Glass Session Cannot Acknowledge - A security alert was acknowledged from a break-glass session; sign in normally to acknowledge it
• Break-Glass Session Cannot Change Designation - A break-glass designation was set or cleared, or a designated member removed, from a break-glass session; sign in normally to change it
• Break-Glass Session Cannot Recover Identity - An assisted identity recovery was requested from a break-glass session; sign in normally to perform it
• Security Alert Acknowledgment Not Permitted - A tenant's security alert was acknowledged on the platform plane, which reads tenant alerts but never acknowledges them
• Compliance Pack Not Licensed - A catalogued compliance pack is locked because the deployment licence does not entitle it: its live evaluation (on either plane, and of one tenant in it), the remediation update, preview, execution and attestation, and both evidence exports are refused, while its stored history, plan, executions and attestations stay readable
• Custody Operation Not On This Plane - A key custody operation was sent to the plane that does not decide it for this tenant on this deployment (on SaaS, a tenant's own key management service is its tenant administrator's, and moves between managed tiers follow the platform administrator's Edition change); the scope is present and nothing was written
• Workload Self-Modification Forbidden - An administrative workload addressed itself in a write (its status, name, keys, bindings or scopes); nothing changed

404 Not Found

• Resource Not Found - The requested resource, key, or endpoint does not exist
• Material Version Not Found - The referenced key material version does not exist
• Compliance Pack Not Found - A well-formed compliance pack identifier names no pack of the running release

405 Method Not Allowed

• Method Not Allowed - The HTTP method is not supported for the endpoint

409 Conflict

• Conflict - The generic conflict: what you receive when the server has nothing narrower to say (a concurrent modification that lost the race, an absent precondition, or an upstream conflict that classified nothing at all). A duplicate identifier is not this type — it carries duplicate-kid
• Credential Endpoint Changed - A credential-only write carried the endpointFingerprint of an endpoint that is no longer the one bound; the endpoint moved after the read, and nothing was sealed
• Invalid Key State - Key exists but is in an invalid lifecycle state for the requested operation
• Key Material Expired - An encryption or signature (or the target of a re-encryption or re-signature) named a key whose current material is past its expiry, or whose expiry cannot be read. Nothing produced, the key unchanged, no Retry-After; it still decrypts and verifies, and rotating it restores protection. A key both expired and exhausted is answered with this type
• Key Material Usage Exhausted - An encryption or signature named a key whose current material has used up its usage limit, a budget of protection operations that decrypt and verify never spend. Nothing produced or counted, the key unchanged, no Retry-After; rotating it restores protection
• Key Protection Limit Reached - A key-metadata update set or cleared expiresAt on a key whose expiry is reached, or maxUsageLimit on a key whose usage limit is used up. A reached limit is final; nothing is written, and rotation is the remedy
• Key Material Without Operations - A key import re-imported an existing key whose stored current material declares no permitted operation (an empty key_ops, which only an earlier release could store). Nothing is written, no Retry-After; rotate or recreate the key
• Stateful Key Exhausted - An XMSS, XMSS^MT, LMS or HSS key can produce no further signature: every one-time index is used, or the key existed in a database that was later restored. Nothing signed, no Retry-After; rotate the key, and its earlier signatures still verify
• Stateful Key Busy - Another request was reserving the same stateful key's next one-time signature and this one did not get the reservation within its bound. Nothing signed, no index spent; carries Retry-After and is safe to retry
• Concurrent Modification - Resource was modified by another request between read and write
• Root Membership Exclusive - A membership would put a platform administrator's identity in a tenant, or a tenant member's identity in the platform tenant; platform administrators reach a tenant only through consented support access. Nothing is written, and the detail is one fixed sentence that names no address
• Session Not Identified - Ending every other session was asked with an access token that names no session (no sid claim), so the calling session cannot be told from the others. Nothing changes; sign in again and repeat the request
• Data Integrity Error - Request violates a data integrity constraint
• Key ID Retired - The requested kid belonged to a key this tenant destroyed; a Key ID is never reused within its tenant. Raised on key creation and import on both planes with the same type; a keystore import reports the entry among its failures with reason KEY_ID_RETIRED and imports the rest
• Duplicate KID - A key that still exists already holds the requested kid for the tenant, in any lifecycle status; a destroyed key's kid is retired instead (Key ID Retired). Raised by the Core API key plane and relayed unchanged by the Admin API tenant-in-path create, which re-presents this same type, so you can branch on it on either plane; that create answers the generic Conflict only on its degenerate arm, when the upstream refusal identified nothing at all
• Cascade Subset Violation - A cascading change would leave dependent policies outside the allowed subset
• Counterparty Type Still Referenced - Counterparty type is still referenced and cannot be deleted
• Credential Install Not Recorded For The Current Declaration - The environment host reported installing a PKCS#11 partition credential for a backend the deployment no longer declares; the report is audited and not recorded, and the host activation stops before the bind
• Token Serial Not Reported By The Declared Backend - Selecting the PKCS#11 token by serial was requested while the declared or configured backend's module reports no token serial (AWS CloudHSM) — on the selector's settings write, the configuration, the declaration or the activation; nothing was written or contacted, and the remedy is to select the token by label
• Key-Protection Backend Activation In Progress - A second activation, a declaration, a withdrawal, a descriptor configuration or a credential replacement was attempted while a deployment backend activation is in flight; nothing was changed or contacted, and the request is retried once that activation ends (a window that has made no progress for 15 minutes is treated as abandoned)
• Key-Protection Backend Activation Window Lost - An activation stopped without recording the bind because its activation window was no longer its own, or the configuration, credential or declaration it read changed while it ran; a re-run reads the configuration that stands now, keeps the keys already recorded for the backend and creates or resolves the missing ones
• Deployment Backend Changed During The Write - A credential replacement was proved, and the configuration, the credential in effect or the declaration had changed by the time it would have been put into effect; nothing was promoted and the credential in effect is unchanged — re-read and retry
• Key Protection Backend Not Configured - The key-protection backend setup has not been completed; carries setupState, no Retry-After
• Marketplace Bootstrap In Progress - Marketplace bootstrap is in progress for the tenant
• Marketplace Edition Unavailable - The Edition a RapidAPI subscription plan maps to cannot be delivered (its managed key-protection tier is not active, or its backend has no room); extensions.edition and extensions.reason name which and why, nothing was created or changed, and the same request answers the same refusal until the Edition can be delivered
• Edition Set By Marketplace Plan - A write would set the Edition or key custody of a RapidAPI marketplace tenant (an Edition assign or clear, a tenant-plane custody move write, a BYOK declare or bind), whose Edition only its subscription plan sets; nothing was written
• Deployment Backend Declaration Is In A Retired Shape - The stored deployment key-protection declaration predates a descriptor collapse and no longer deserializes; carries backendType and no coordinate, and no Retry-After
• Managed Tier Key Capacity Exhausted - Establishing per-tenant key custody would take the Edition tier's carrier past the backend's published key-object ceiling; names the tier and the object counts, and nothing was written
• Unfit Key Material Object - The object under a tenant's key-encryption-key label is not a sensitive, non-extractable AES-256 key, so it is refused rather than adopted; nothing created and nothing adopted. PKCS#11 only
• Foreign Environment Claim - The PKCS#11 security domain carries another environment's claim, or holds bootstrap-labelled key-encryption keys under no claim at all; nothing created and nothing adopted. Names neither environment and neither fingerprint. PKCS#11 only — the Cloud KMS families carry no claim marker
• License Already Imported - A license with the artifact's licenseId has already been imported into this installation; exactly one is stored, and a renewal is a new license
• License Installation Identity Unavailable - The licence server cannot establish which installation it is (the trial sentinel is missing, unreadable, fails its integrity check, or carries no canonical installation ID); license import, the activation request, statement reads and signed compliance evidence are refused until the sentinel is restored
• Usage Statement Already Issued - A usage statement was asked for a month that already has one in this scope and the request names nothing to supersede; the detail names the month, and the remedy is a correction naming the current statement
• Usage Statement Already Superseded - A usage-statement correction names a statement another retained statement already supersedes; the chain is kept linear so the month keeps one current statement, and the detail names the leaf to correct instead
• Usage Statement Coverage Unverifiable - A usage statement was asked for while the deployment's installation cannot be vouched for (the trial sentinel is missing or invalid); no statement can bound its completeness, and every month is refused until the sentinel is restored
• Usage Statement Period Not Covered - A usage statement was asked for a month that ends before the first day whose rows this deployment's usage store holds (the later of the installation day and the oldest retained day); the detail names that day, and the month never becomes issuable
• Usage Statement Not Finalizable - A usage statement was asked for a month that is not yet FINAL; the detail names the month and whether it is OPEN or PROVISIONAL, and the request succeeds unchanged once the month finalizes
• Usage Export Concurrency Limit - A usage export was started while the per-actor or per-plane-and-tenant-scope cap on in-flight exports was already reached; nothing is created, the detail names the cap, and the remedy is to wait for an export to finish. A 409 and not a 429, because a 429 would reach the caller through the Admin API relay as a 502
• Compliance Remediation Basis Changed - A compliance remediation step was confirmed with a basis that no longer matches the keys or the evaluation; nothing ran, and the remedy is to preview again
• Compliance Remediation Conflict Unacknowledged - The chosen remediation targets would newly fail items of another licensed pack that the request did not acknowledge; the conflicts are listed and nothing ran
• Compliance Remediation Execution In Progress - A compliance remediation action was confirmed under a new Idempotency-Key while another execution of the same action is still running; one action runs at most once at a time, nothing ran, and the remedy is to wait for the running execution and preview again
• Idempotency Key In Progress - A request was retried with the same Idempotency-Key and body while the first one is still running; nothing ran, and the retry succeeds with the stored result once the first finishes
• Material Version Moved - A key rotation found the key at another material version than the one it advances from, because another rotation advanced it first; nothing was changed, and a resend under the same Idempotency-Key repeats the refusal
• Bootstrap Workload Exists - The first platform workload was asked for from the environment host while a platform workload that is not REVOKED exists (a SUSPENDED one included); nothing registered
• Issuer Subject Already Bound - The trusted issuer and subject are already bound to an administrative workload or a cryptographic actor of the tenant
• Workload Credential Conflict - The public key is already registered on a workload of the deployment
• Workload Credential Not Active - A workload key that is rotating out or revoked cannot be rotated
• Workload Name Conflict - A live administrative workload of the tenant already uses the name
• Workload Revoked - The administrative workload is revoked, which is terminal; it cannot be changed or reactivated
• Authenticator Removal Would Lock Out - Removing one of your own authenticators, or your password, would leave a membership with no way to sign in
• Last Platform Super Administrator - The change would leave no active PLATFORM_SUPER_ADMIN able to sign in by an ordinary route (password + TOTP, a usable passkey or an approved platform identity provider); the break-glass entry does not count, and nothing is changed
• Platform Super Administrator Role Immutable - PLATFORM_SUPER_ADMIN is never edited or deleted: its scopes are the platform catalogue's
• Federated Credential Recovery - An identity federated through OIDC or SAML is recovered by its identity provider, not by assisted recovery
• Recovery Entry Unreachable - An identity holding no active membership is not recovered: its enrolment could never be completed. A person who never activated is re-sent the activation link instead
• Tenant Recovery Request Required - On a deployment ANKA operates, an identity of a customer tenant is recovered only to answer a pending request one of its tenants filed; nothing was changed, and the refusal is audited DENIED
• Security Alert Already Acknowledged - The security alert was already acknowledged; the first acknowledgment is kept
• Ownership Recovery Identity Ineligible - Deployment-ownership recovery named an identity that holds a tenant membership, or holds no platform membership or one it has not accepted
• Instance Not Claimed - Deployment-ownership recovery ran on an environment nobody has claimed yet; the first platform administrator is created by the instance claim
• Instance Already Claimed - envctl.sh <env> claim-code ran on an environment that already has its first platform administrator; no claim code is minted. A claim start on a claimed environment answers Instance Claim Code Invalid instead
• Passkey Unavailable On Origin - A passkey ceremony was asked for while the console is open on an address that is not the Management host name (such as the host's IP address); no Retry-After

Key custody moves. A key custody move re-wraps every key of a tenant under another key-encryption key. Its operations answer these types, and each one is raised before anything is written:

• Custody Move In Progress - The tenant already has a scheduled or running custody move, so a second move, a BYOK change, an Edition change or a lifecycle verb on a tenant in MAINTENANCE is refused until it ends
• Custody Move State Conflict - The move is not in a state the operation applies to (for example a cancel of a move that already started)
• Custody Destination Is The Source - A move started, or its destination chosen, names the key protection the tenant's keys are already on: its managed tier, the deployment backend it inherits, or the own key it is bound to
• Custody Move Past Its Swap - An abort of a window whose keys are already live on the destination, or of an online move; it only completes, and a roll back returns to the key it left
• Custody Roll Back Unavailable - The key-encryption key a roll back would return to is past its 30-day retention or was retired by a compromise re-key
• Custody Move Awaits Tenant Consent - On SaaS, a downgrade off a tenant's own key management service is scheduled by its tenant administrator, not by the platform administrator
• Tenant Not Eligible For A Custody Move - The tenant is suspended or closed; its custody does not move

The key service answers the administration service with its own types while a move runs. They never reach a client, and an operator sees their effect on the move's state: Custody Swap Incomplete, Custody Write Conflict, Custody Stage Not Verified, Custody Lineage Not Current, Custody Material Unreadable and Custody Rollback Conflict.

Key-encryption key destruction. A platform administrator destroys a tenant's retired key-encryption key at its provider or HSM, and may cancel the destruction while it is pending. Each refusal leaves the key in the status it had, and none changes anything at the provider:

• Key-Encryption Key Not Retired - A destruction was asked for a key-encryption key that is not retired
• Key-Encryption Key Destruction Already Requested - The key-encryption key is already pending destruction, or already destroyed
• Key-Encryption Key Still Retained - The key-encryption key is still inside the 30-day retention a roll back may return to it in
• Key-Encryption Key Still Wraps Key Material - A recount found key material that is, or may be, wrapped under the key-encryption key
• Key Object Still In Use - Another lineage entry of the tenant that is not retired names the same key object
• Custody Move In Progress - A key custody move of the tenant is open, so none of its key-encryption keys is destroyed
• Key-Encryption Key Carrier Not Bound - The managed tier holding the key-encryption key is bound to another key management service now
• Key Object Not Resolved - The HSM holds more than one object under the key-encryption key's recorded label, or one carrying another identifier
• Provider Permission Missing - The managed tier's credential lacks the permissions to destroy a key, or to cancel its destruction; extensions.step = PROVIDER_DESTRUCTION
• Key-Encryption Key Destruction Not Pending - A cancel was asked for a key-encryption key whose destruction is not pending
• Key-Encryption Key Destruction In Flight - A cancel was asked while the destruction request may still be waiting for its provider
• Key-Encryption Key Already Destroyed - The provider has already destroyed the key-encryption key, so its destruction cannot be cancelled

412 Precondition Failed

• Precondition Failed - A request precondition was not satisfied

413 Payload Too Large

• Payload Too Large - A JSON request body exceeds the ceiling of the route it targets (a per-service ceiling, or one derived from the operator setting that bounds the payload); refused before it is read, after authentication and authorization
• Request Parameters Too Large - A form body exceeds the size the server parses into parameters
• License Artifact Too Large - License artifact exceeds the maximum accepted size
• WebAuthn Metadata Too Large - An uploaded FIDO metadata file exceeds 32 MiB; the loaded metadata is unchanged

415 Unsupported Media Type

• Unsupported Media Type - Request Content-Type is not supported by the endpoint

421 Misdirected Request

• Misdirected Request - The request reached a Core API deployment role that does not serve its route, and was refused before any processing: no handler ran, no usage was counted, no audit event was recorded. A request through the platform's edge is routed to the right role and never receives it; no Retry-After

422 Unprocessable Entity

• Unprocessable Entity - Semantically incorrect content (malformed JWE/JWS, header validation failures, and value-level rules a well-formed body cannot satisfy — an inverted validFrom/validUntil window, or a negative maxUsage/rateLimitPerMinute on a constraint policy)
• Unsupported PKCS#7 Format - Valid PKCS#7 structure that cannot be converted as requested (COMPACT for several actors, more actors than one conversion accepts, an unsupported identifier, recipient type or algorithm)
• Missing Key for a PKCS#7 Signer or Recipient - One or more signers or recipients of a PKCS#7 conversion have no tenant key admissible for their role (a certificate imported alone only verifies); extensions.unresolvedActors names every one
• Decryption Failed - Supplied key could not decrypt the PKCS#7 content (wrong recipient key or corrupted ciphertext)
• Purpose Required - Key purpose could not be inferred and must be declared explicitly
• Tenant's Own Key Not Destroyed - The key-encryption key is the tenant's own key at its key management service, which the platform never destroys
• Tenant Holds The Deployment Key - The tenant is a bootstrap tenant, whose key-encryption keys are the deployment's own
• Key Held On The Deployment Backend - The key-encryption key is on a Cloud KMS deployment backend, in the customer's account
• Rotation Purpose Violation - Rotation cannot change the key purpose
• Key Operations Narrowing Forbidden - Rotation may only preserve or widen the current material's key_ops, never narrow it
• Rotation Security Downgrade - Rotation target is a security downgrade from the current key
• Dual Not Applicable - Dual projection is not applicable to a single-purpose key
• Composite Wire Shape Mismatch - Composite message wire shape does not match the key definition
• Composite Component Algorithm Mismatch - Composite component algorithm does not match the key definition
• Composite KDF Mismatch - The composite JWE's protected anka_kdf is absent, unknown, or not the KDF the key material records
• Invalid State Transition - Requested lifecycle state change is not permitted from the current state
• Invalid Material Transition - Requested key material status change is not allowed from its current status
• Purpose Mismatch - Key purpose does not match the purpose required by the operation
• Algorithm Not Permitted for Operation - Key algorithm is not permitted for the operation under the active policy
• Tenant Type Restriction - Operation is not allowed for this tenant's type
• Tenant Policy Subset Violation - Tenant policy is not a subset of the parent policy
• Lifecycle Policy Subset Violation - Lifecycle policy is not a subset of the inherited policy
• Import Operation Not Orchestrable - Import operation cannot be orchestrated under the requested use case
• Composite-Pair Operation Not Supported - Composite-pair operation requires a multi-key use case that is not yet supported
• License Artifact Invalid - License artifact failed validation: it is malformed, its signature could not be verified, or it names a compliance pack the running release does not define
• License Schema Version Unsupported - License artifact declares a payload schema version this deployment does not support
• License Signing Key Unknown - License artifact names, in signature.kid, a signing key the running release does not trust; refused before the signature is checked, and the remedy is a re-issue under a trusted key or an upgrade to a release that trusts it
• License Installation Mismatch - License artifact is authentic but was issued for a different installation (its signed installationId is not this installation's); the remedy is a license issued from this installation's activation request
• License Expired - License artifact has passed its validity period
• Compliance Evidence Too Large - The signed compliance evidence document of a pack would exceed its 16 MiB bound, so nothing was signed
• Key Coordinate Is Not Valid For This Backend - The submitted keyId does not parse under the declared backend family's own grammar; carries field and backendType, and never the submitted value
• Custody Destination Unsupported - A key custody move names a destination the platform cannot move the tenant's keys to, or a key-encryption key rotation or rotation period is asked of a carrier whose key its provider or its owner rotates
• Earlier Start Reason Required - On SaaS, a custody window for an Edition change scheduled earlier than the platform's default notice carries no earlierStartReason
• Tenant Name Confirmation Required - A move back to the deployment's key protection backend without the tenant's name typed exactly in confirmTenantName
• Custody Destination Invalid and Custody Source KEK Required - answered by the key service to the administration service during a custody move, never to a client; the window reopens the tenant on its source
• Key-Protection Property Not Stored On This Plane - A key-protection declaration in the driver form carries a property the driver accepts and the plane has no place to keep; extensions.field names it and nothing was written
• Backend Endpoint Requirement Not Satisfied - The declared backend requires a connection endpoint and none was supplied, accepts none and one was, or the endpoint's host is not a host of the backend's vendor; carries field and never the submitted value
• BYOK Credential Self-Test Failed - A new BYOK access credential did not pass verification against the declared key, so it was not stored and the credential in force remains; carries reason and check, sends no Retry-After
• Key-Material Backend Bind Verification Failed - A BYOK bind's self-test reached the declared backend and its answer is durable (refused credential or operation, round-trip mismatch, missing key, unusable declaration); the reason extension names it and waiting will not change it
• Bootstrap Tenant Uses Deployment Custody - A bootstrap tenant other than the platform tenant was named as the target of an Edition assignment or clear, or of a BYOK declare, bind, credential rotation or revert; its keys are held by the deployment's backend; nothing was read or contacted, and the one write is a FAILURE audit row
• BYOK Declared Key Unusable - A new BYOK access credential could not find or address the declared key (KEY_ABSENT, DESCRIPTOR_INVALID, SECURITY_DOMAIN_ABSENT), so it was not stored and the credential in force remains; carries reason and check, sends no Retry-After
• Backend Key Coordinate Requirement Not Satisfied - The declared DEPLOYMENT backend requires a key coordinate and none was supplied, or accepts none and one was; carries field and never the submitted value. Not a byok- type: the refusal cannot occur on the per-tenant plane, where every family requires a coordinate
• Timestamping Cannot Be Required - A configuration write would leave tenants required to timestamp over a connection that cannot produce one; platform writes carry affectedTenantCount and deploymentDefaultAffected and can be repeated with ?acknowledgeAffectedTenants=<count>, the tenant write carries neither and has no acknowledgement
• Alert Bounds Out Of Order - A platform settings write or reset would leave ALERT_SIGNIN_FAILURES_CRITICAL_PER_HOUR below ALERT_SIGNIN_FAILURES_WARNING_PER_HOUR; carries field and relatedField, never a value, and cannot be acknowledged
• Backup Run Not Recorded - An off-host copy was declared with an archive SHA-256 that is not the archive of any successful backup run the platform recorded; nothing is recorded and the refusal is audited
• Compliance Remediation Step Not Applicable - The confirmed step is not one the compliance remediation action offers; nothing ran
• Compliance Remediation Rotation Admissible - A successor key was confirmed for a key that can be rotated under the same Key ID; nothing ran
• Compliance Attestation Not Applicable - An attestation named an item the platform measures, or one that is not in the pack; only customer-attested and unverified items are attestable, and nothing was stored
• Idempotency Key Reused - An Idempotency-Key was reused with a different request; nothing ran
• Rotation Execution Mismatch - The key service's execution identifier for a rotation already names a different rotation; nothing was written. A platform defect when seen on the Admin API, never a defect of the request
• Rotation Interval Exceeds Its Ceiling - A rotation-schedule interval is longer than the deployment maximum, the maximum cryptoperiod of the entitled compliance packs, or the default of a compliance-locked deployment; extensions.ceiling names the bound and nothing was stored
• Rotation Schedule Without Cadence - Automatic rotation was enabled on a key to which no rotation interval applies and with no usage option on; nothing was stored
• Usage Rotation Without Soft Limit - rotateOnSoftUsageLimit was turned on for a key with no soft usage limit; nothing was stored
• Usage Rotation Without Usage Limit - rotateOnUsageExhaustion was turned on for a key with no maximum usage limit; nothing was stored
• Workload Scope Not Admissible - A scope an administrative workload of that tenant may never hold; extensions.inadmissibleScopes names every one and nothing is stored
• Authentication Posture Not Admissible - A tenant authentication posture the deployment does not allow, or that no member could satisfy; extensions.field names the member
• Break-Glass Designation Ineligible - A membership that cannot be a break-glass identity was designated, or a designated one was linked to an identity provider or restricted to it
• Passkey Property Not Established - A tenant requires an attested, hardware-backed or device-bound passkey and the registration could not establish it; extensions.reason says why
• WebAuthn Metadata Refused - An uploaded FIDO metadata file was not admitted; extensions.reason names the failed check

428 Precondition Required

• Precondition Required - The write carried no precondition against a resource that already has a stored value, so it was refused rather than allowed to overwrite it; the remedy is to read the current version and send it back, never to re-read after a change nobody made

429 Too Many Requests

• Too Many Requests - Request rate limit exceeded for the endpoint
• Refresh Cooldown Active - A snapshot refresh cooldown is still active
• Key Protection Rate Limited - Too many key-protection operations; retryable after the Retry-After interval
• Log Fingerprint Rate Limited - 10 log fingerprint computations by this caller in the current minute or 200 in the current day; nothing was computed or recorded, retry after Retry-After
• Log Search Rate Limited - 30 platform log searches by this caller in the last minute; nothing was searched or recorded, retry after Retry-After

4xx Generic

• Client Error - General client error fallback for unspecified 4xx status codes

Federated-login refusals

Two refusals are specific to identity federation, and they are separate types because the remedies belong to different people.

409 federation-domain-verification-required

Enabling an identity provider was refused because the applicable verified email-domain set is empty. The provider is fine; the deployment has not yet declared which email domains it federates, and a provider enabled in that state would refuse every sign-in it received.

extensions.prerequisite carries VERIFIED_DOMAIN_REQUIRED.

Remedy: declare at least one email domain, then enable again. On a customer-operated deployment declaring is verifying — there is no DNS challenge.

This is deliberately a different type from the other 409 the same operation can return (a provider with no passing self-test): "run a self-test" and "declare a domain" are different actions performed by potentially different people, and collapsing them would force the caller to read the detail to find out which.

403 federation-not-entitled

The tenant's licensed edition does not include tenant-configured identity federation.

This is not an authorization problem, and the detail deliberately contains none of "permission", "not authorized", "forbidden" or "scope". The caller is inside their tenant boundary and holds the right scope; what is missing is commercial. Reading it as an RBAC failure sends a tenant administrator to audit their own roles for a problem that is not there, and they will not find it.

Remedy: contact your account manager. A tenant that cannot configure its own provider is still able to sign in through the identity provider configured for the deployment — this refusal is not "single sign-on is unavailable to you".

The detail never discloses whether a licence read failed. The entitlement read (GET /api/v3/admin/tenants/{tenantId}/idp/entitlement) does report that, as resolution: FLOORED, because it answers an already-scoped administrator asking about their own tenant rather than an attempted write. The asymmetry is intentional.

Server Errors (5xx)

Server errors indicate that the server failed to fulfill a valid request.

500 Internal Server Error

A 500 means the platform could not attribute the failure to your request. It is a server fault, and it is not retryable — a transient condition is reported as a 503 with Retry-After, never as a 500. A condition that has an owning error type is reported as that type, with its own status.

• Internal Server Error - Unexpected server-side error occurred
• Cryptographic Error - Internal cryptographic operation failure
• Repository Error - Database or storage layer operation failed
• Admin Operation Failed - An administrative operation failed on the server
• Keystore Error - A keystore operation failed on the server
• Data Access Error - A database or storage operation failed while handling the request

501 Not Implemented

• Not Implemented - Requested functionality is not yet implemented

502 Bad Gateway

• Upstream Service Unavailable - An internal upstream dependency failed or is unreachable; retryable, honor Retry-After when present
• Log Store Unavailable - A platform log search got no usable answer from the log store (unreachable, TLS verification failed, a non-200 status, no answer in 10 seconds, or more than 8 MiB); no line returned, the search still recorded
• Usage Telemetry Unresolved - A metered-consumption, export or statement read could not be obtained from the licence server; never a report of zero usage
• Key-Encryption Key Provider Failed - The provider or HSM holding the key-encryption key refused a destruction before changing anything, or refused or gave no usable answer to a cancel; extensions.provider names it by role

503 Service Unavailable

• Service Unavailable - Service temporarily unavailable due to maintenance, overload, or dependency failures
• Async Not Usable - Asynchronous service temporarily unavailable or disabled
• Data Source Unavailable - A required data source is temporarily unavailable
• Dependency Not Ready - A backing dependency is unavailable, including the audit trail: a crypto operation, a login or token call, a PQC handshake or a platform-statistics refresh whose audit record cannot be confirmed is refused instead of answered; nothing was returned, retryable, sends Retry-After
• Marketplace Credential Unavailable - A marketplace request could not be judged because the RapidAPI gateway credential could not be read; not an authentication failure, sends Retry-After: 30
• Marketplace Temporarily Disabled - The marketplace integration is temporarily disabled
• Policy Lock Timeout - A policy write could not take its lock on the deployment policy row within the five-second bounded wait because a concurrent deployment policy write held it; nothing was changed, retryable, sends Retry-After: 5
• PQC Session Capacity Reached - The platform has temporarily reached its capacity for new PQC transport sessions; the handshake was refused before any key exchange, retry after Retry-After
• Snapshot Stale - The audit snapshot is stale and a fresh one is not yet available
• Stats Snapshot Unavailable - The statistics snapshot is not available yet
• Key Protection Backend Unavailable - The key-protection backend is bound but momentarily unreachable; retryable, sends Retry-After
• Key Protection Backend Misconfigured - The key-protection backend is not usable as configured; durable, deliberately sends NO Retry-After
• Backend Key Provisioning Unavailable - The per-tenant key-encryption-key phase got no usable answer in time from the deployment backend, or the backend asked it to slow down; keys created before it are kept and adopted, retry after Retry-After
• Backend Self-Test Unavailable - The deployment backend's self-test (activation or credential write) could not reach the backend in time, or the backend asked it to slow down; nothing was learned, retry after Retry-After
• Tier Bind Self-Test Unavailable - A managed tier's bind self-test could not reach the tier's backend in time, or the backend asked it to slow down; the tier is unchanged, retry after Retry-After
• Key-Material Backend Bind Verification Unavailable - A BYOK bind's self-test could not reach the declared backend in time, or the backend asked it to slow down; nothing was learned, retry after Retry-After
• BYOK Credential Self-Test Unavailable - The tenant's key service could not be reached to verify a new BYOK access credential; nothing was stored, retryable, sends Retry-After
• Tenant KEK Unavailable - A tenant's own key-encryption key could not be reached or provisioned on the declared backend, so the key operation is refused rather than deferred. Retryable, sends Retry-After. Extension members: declaredBackend — the token the operator declared (luna, softhsm, aws-kms, …), never the provider scalar it strips to, so the refusal names what the operator chose rather than what the runtime dispatches on; and reason, the machine-readable cause. declaredBackend is omitted when no backend is declared at all.
• Secret Custody Unavailable - A per-tenant secret-custody operation could not reach or provision that tenant's own custody key. Retryable, sends Retry-After. Deliberately distinct from backend-not-bound, which the deployment custody tier keeps unchanged: the two planes fail for different reasons and a client that needs to distinguish them cannot do so from one type. There is no fallback onto the deployment key — the refusal is terminal and the caller's transaction rolls back, leaving no partially sealed row.
• Log Fingerprint Rate Bound Unavailable - The shared counter of the log fingerprint rate bound could not be read, so nothing was computed; sends Retry-After
• Log Fingerprint Audit Unavailable - A log fingerprint computation could not be recorded in the audit trail, so no fingerprint was returned; retryable
• Log Search Audit Unavailable - A platform log search could not be recorded in the audit trail, so no log line was returned; retryable
• Compliance Evidence Package Busy - The Admin API instance is already preparing a compliance evidence package, the one it prepares at a time; refused before the licence server is read, nothing issued or recorded, sends Retry-After: 15
• Usage Accounting Unavailable - A protect use that reaches its key's soft or maximum usage limit could not record that crossing; nothing was counted or produced, retryable, sends Retry-After: 5
• Authentication Policy Unreadable - A stored authentication posture holds a value the running release does not know, so the operation is refused rather than decided on a weaker policy; nothing was changed, no Retry-After
• Tenant In Maintenance - The caller's tenant is temporarily unavailable for cryptographic and key operations while a maintenance window moves its keys; nothing was executed, sends Retry-After: 300, and is answered only to an authenticated caller of that tenant (any other caller gets its usual 401 or 403). An availability refusal, not a denial: retry, do not re-authenticate

504 Gateway Timeout

• Upstream Service Timeout - An internal upstream dependency did not respond within the operation's deadline; retryable
• Rotation Outcome Unknown - A key rotation was sent to the key service and no answer arrived, so it may have been applied; names the rotation in extensions.executionId, and a resend under the same Idempotency-Key returns its outcome without rotating twice
• Gateway Timeout - An upstream dependency did not respond within the operation's deadline; retryable

Error Handling Best Practices

Retry Strategy

• 4xx errors: Generally should NOT be retried without fixing the request
• 500 errors: NOT retryable. A 500 is an unattributable server fault, not a transient one — the identical request produces the identical result. Record the correlation identifier and report it instead
• 502/504 errors: Retryable - honor the Retry-After header when present (emitted while the circuit breaker toward the failing upstream is open), otherwise apply exponential backoff
• 503 errors: Retryable when a Retry-After header is present — wait the stated delay. A 503 without Retry-After signals a durable misconfiguration (for example key-protection-backend-misconfigured) and must not be retried: retrying re-presents the same bad configuration, and against a PKCS#11 token a repeated wrong PIN locks the token's user PIN
• 429 errors: Honor the Retry-After header before retrying

Error Logging

Always log the following from error responses:

• correlationId - For correlation with server-side logs
• timestamp - For temporal analysis
• type - For programmatic error handling
• detail - For debugging context

Programmatic Error Handling

This pattern applies to API errors — every response carrying an application/problem+json body. It does not apply to the browser-redirect error surface, which has no body and therefore no type to dispatch on; those failures are read from the error query parameter by the console, not by a programmatic client.

// Example: dispatch on the RFC 9457 `type` URI
switch (problemDetails.getType().toString()) {
    case "https://docs.ankatech.co/errors/deployment-license-expired":
        // Deployment-wide, not caller-specific. Reads still succeed; do not retry the write.
        surfaceReadOnlyModeToOperator();
        break;
    case "https://docs.ankatech.co/errors/payment-required":
        redirectToPaymentPortal();
        break;
    case "https://docs.ankatech.co/errors/validation":
        displayFieldErrors(problemDetails.getDetail());
        break;
    case "https://docs.ankatech.co/errors/not-found":
        handleMissingResource();
        break;
    default:
        logErrorAndNotifyUser(problemDetails);
}

Rate Limiting

When encountering rate limit errors:

1. Check the X-RateLimit-Remaining header
2. Respect the X-RateLimit-Reset timestamp
3. Implement client-side throttling
4. Consider upgrading your plan for higher limits

Additional Resources

• Developer Hub Reference - General error handling and endpoint documentation
• Authentication on the Developer Hub - Authentication and authorization
• Policy Cache Monitoring on the Developer Hub - Monitoring, observability, and rate limit information
• Error Catalog^* - Deployment and operational errors: exit codes, bootstrap, runtime and infrastructure failures
• Support Portal - Contact support for persistent issues

Need Help?

If you encounter an error not documented here or need assistance resolving persistent errors:

1. Check the correlationId from the error response
2. Review server status at status.ankatech.co
3. Contact support with the error details and correlationId
4. Consult the Developer Hub Reference for endpoint-specific requirements