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.

Quick Reference Table

Error Response Format

All API errors follow the RFC 7807 Problem Details standard and are returned with Content-Type: application/problem+json. 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 7807:

• 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 recipient metadata; 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, unauthorized_client, unsupported_grant_type, invalid_scope, tenant_selection_required, access_denied) use an underscore type suffix so the RFC 7807 type matches the RFC 6749 error code exactly.

Where extension members live depends on which service answered

RFC 7807 — and its successor RFC 9457 — 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 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 and its recipient metadata:

{
  "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 six codes and their remedies.

This is a second error representation, not an exception to the RFC 7807 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 7807 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 7807 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
• Invalid PKCS#7 Structure - Provided file is not a valid PKCS#7/CMS structure
• Missing Request Part - Required multipart form data or request parameters are missing
• 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
• Key Operation Incompatible - Requested operation is incompatible with the key's type or algorithm
• 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
• 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
• Tenant Selection Required - OAuth 2.0: OAuth 2.0 credentials map to multiple tenants; a tenant must be selected

401 Unauthorized

• Unauthorized - Missing or invalid authentication credentials
• Invalid Client - OAuth 2.0: OAuth 2.0 client authentication failed
• Unauthorized Client - OAuth 2.0: OAuth 2.0 client is not authorized to use the requested grant type

402 Payment Required

• Payment Required - License expired or usage limits exceeded, payment or renewal needed

403 Forbidden

• Forbidden - Authenticated but lacking permission for the requested operation
• SaaS-Only Feature - Feature is available only in the ANKASecure SaaS deployment
• Unsupported Principal Type - Authenticated principal type is not supported for the operation
• Access Denied - OAuth 2.0: OAuth 2.0 authorization request was denied

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

405 Method Not Allowed

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

409 Conflict

• Conflict - Request conflicts with current resource state (duplicate keys, concurrent modifications)
• Invalid Key State - Key exists but is in an invalid lifecycle state for the requested operation
• Concurrent Modification - Resource was modified by another request between read and write
• Data Integrity Error - Request violates a data integrity constraint
• Duplicate KID - A key with the requested kid already exists for the tenant
• Cascade Subset Violation - A cascading change would leave dependent policies outside the allowed subset
• Deployment Policy Locked - The deployment policy is locked and cannot be modified
• Counterparty Type Still Referenced - Counterparty type is still referenced and cannot be deleted
• 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

412 Precondition Failed

• Precondition Failed - A request precondition was not satisfied

413 Payload Too Large

• Payload Too Large - Request payload exceeds configured size limits
• License Artifact Too Large - License artifact exceeds the maximum accepted size

415 Unsupported Media Type

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

422 Unprocessable Entity

• Unprocessable Entity - Semantically incorrect content (malformed JWE/JWS, header validation failures)
• Unsupported PKCS#7 Format - Valid PKCS#7 structure but feature not yet supported (e.g., multiple signers/recipients)
• Missing Private Key - Required private key not found in keystore for PKCS#7 conversion
• 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
• 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
• 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
• Invalid Stable KID Transition - Requested stable kid 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; its signature could not be verified
• License Deployment Mismatch - License artifact was issued for a different deployment
• License Expired - License artifact has passed its validity period

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

4xx Generic

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

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

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
• Marketplace Temporarily Disabled - The marketplace integration is temporarily disabled
• 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
• Audit Event Publishing Failed - A required audit event could not be published; the operation was not completed

504 Gateway Timeout

• Upstream Service Timeout - An internal upstream dependency did not respond within the operation's deadline; retryable
• 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 7807 `type` URI
switch (problemDetails.getType().toString()) {
    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
• 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