Skip to content

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

HTTP Code Error Type URI
400 Invalid Input https://docs.ankatech.co/errors/invalid-input
400 Missing Request Part https://docs.ankatech.co/errors/missing-request-part
400 Validation Error https://docs.ankatech.co/errors/validation
401 Unauthorized https://docs.ankatech.co/errors/unauthorized
402 Payment Required https://docs.ankatech.co/errors/payment-required
403 Forbidden https://docs.ankatech.co/errors/forbidden
404 Resource Not Found https://docs.ankatech.co/errors/not-found
409 Conflict https://docs.ankatech.co/errors/conflict
413 Payload Too Large https://docs.ankatech.co/errors/payload-too-large
422 Unprocessable Entity https://docs.ankatech.co/errors/unprocessable-entity
422 Ciphertext Integrity Failure https://docs.ankatech.co/errors/ciphertext-integrity-failure
422 Invalid Key State https://docs.ankatech.co/errors/invalid-key-state
4xx Client Error (Generic) https://docs.ankatech.co/errors/client-error
500 Internal Server Error https://docs.ankatech.co/errors/internal
500 Cryptographic Error https://docs.ankatech.co/errors/crypto
500 Repository Error https://docs.ankatech.co/errors/repository
501 Not Implemented https://docs.ankatech.co/errors/not-implemented
503 Async Not Usable https://docs.ankatech.co/errors/async-not-usable
5xx Server Error (Generic) https://docs.ankatech.co/errors/server-error

Error Response Format

All errors follow a consistent JSON structure:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "detail": "Additional context about the error",
    "timestamp": "2025-01-15T10:30:00Z",
    "traceId": "550e8400-e29b-41d4-a716-446655440000",
    "type": "https://docs.ankatech.co/errors/error-type"
  }
}

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
  • Missing Request Part - Required multipart form data or request parameters are missing
  • Validation Error - Request passed JSON parsing but failed field validation rules

401 Unauthorized

  • Unauthorized - Missing or invalid authentication credentials

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

404 Not Found

409 Conflict

  • Conflict - Request conflicts with current resource state (duplicate keys, concurrent modifications)

413 Payload Too Large

422 Unprocessable Entity

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

501 Not Implemented

503 Service Unavailable

5xx Generic

  • Server Error - General server error fallback for unspecified 5xx status codes

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
  • 503 errors: Should be retried after the delay specified in Retry-After header

Error Logging

Always log the following from error responses: - traceId - For correlation with server-side logs - timestamp - For temporal analysis - code - For programmatic error handling - detail - For debugging context

Programmatic Error Handling

// Example: Handling specific error codes
switch (errorResponse.getCode()) {
    case "PAYMENT_REQUIRED":
        redirectToPaymentPortal();
        break;
    case "VALIDATION_ERROR":
        displayFieldErrors(errorResponse.getDetail());
        break;
    case "NOT_FOUND":
        handleMissingResource();
        break;
    default:
        logErrorAndNotifyUser(errorResponse);
}

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

Need Help?

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

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