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 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.

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
• 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
• 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

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

• 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
• 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
• 5xx errors: May be retried with exponential backoff
• 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: Should be retried after the delay specified in Retry-After header
• 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

// 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