Common Errors & Solutions

Frequently encountered errors when using AnkaSecure and how to resolve them.

---

Authentication Errors

AUTH_001: Token Validation Failed

Symptom:

{
  "error": "AUTH_001",
  "message": "Token validation failed: token expired",
  "timestamp": "2025-12-26T10:15:30Z"
}

HTTP Status: 401 Unauthorized

Common Causes: - JWT token expired (1-hour lifetime) - API key invalid or revoked - Token signature invalid

Solutions:

1. For JWT tokens: Refresh token before expiration

   curl -X POST https://api.ankasecure.com/api/v1/auth/refresh \
     -H "Authorization: Bearer REFRESH_TOKEN"
   

2. For API keys: Verify key is correct

   # Check API key in environment
   echo $ANKASECURE_API_KEY
   # Verify matches Admin Console
   

3. Regenerate API key: Via Admin Console → Applications → Regenerate

See authentication guide →

---

AUTH_003: Access Denied

Symptom:

{
  "error": "AUTH_003",
  "message": "Access denied: key belongs to different tenant"
}

HTTP Status: 403 Forbidden

Common Causes: - Trying to access another tenant's resources - X-Tenant-ID header doesn't match JWT claim - Insufficient permissions

Solutions:

1. Verify tenant ID:

   # Ensure X-Tenant-ID matches your tenant
   curl https://api.ankasecure.com/api/v1/crypto/encrypt \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "X-Tenant-ID: YOUR_TENANT_ID"  # Must match JWT
   

2. Check permissions: Contact tenant admin to grant required role

---

Key Management Errors

KEY_001: Key Not Found

Symptom:

{
  "error": "KEY_001",
  "message": "Key not found: my-key-123"
}

HTTP Status: 404 Not Found

Common Causes: - Key ID doesn't exist - Typo in key ID (case-sensitive) - Key belongs to different tenant

Solutions:

1. List available keys:

   curl https://api.ankasecure.com/api/v1/key-management/keys \
     -H "Authorization: Bearer YOUR_TOKEN"
   
   # Or via CLI
   ankasecure-cli key list
   

2. Verify key ID (case-sensitive):

   // ❌ WRONG: Uppercase
   .keyId("MY-KEY-123")
   
   // ✅ CORRECT: Matches created key
   .keyId("my-key-123")
   

3. Generate missing key:

   ankasecure-cli key generate \
       --algorithm ML-KEM-768 \
       --key-id my-key-123
   

---

KEY_003: Key Already Exists

Symptom:

{
  "error": "KEY_003",
  "message": "Key ID already exists: duplicate-key"
}

HTTP Status: 409 Conflict

Solutions:

1. Use unique key ID:

   # Add timestamp or UUID for uniqueness
   ankasecure-cli key generate \
       --algorithm ML-KEM-768 \
       --key-id "customer-key-$(date +%Y%m%d-%H%M%S)"
   

2. Delete existing key (if replacing):

   ankasecure-cli key delete --key-id duplicate-key
   # Then create new key with same ID
   

---

Cryptographic Errors

CRYPTO_001: Ciphertext Integrity Failure

Symptom:

{
  "error": "CRYPTO_001",
  "message": "Ciphertext integrity check failed: authentication tag mismatch"
}

HTTP Status: 422 Unprocessable Entity

Common Causes: - Ciphertext modified or corrupted - Wrong decryption key used - Encoding issues (Base64)

Solutions:

1. Verify ciphertext not modified:

   # Compare checksums (before and after transmission)
   sha256sum ciphertext.enc
   

2. Check Base64 encoding:

   // ✅ CORRECT: Proper Base64 encoding
   String plaintext = Base64.getEncoder().encodeToString(data.getBytes());
   
   // ❌ WRONG: Plain string (not Base64)
   String plaintext = data;
   

3. Use correct key: AnkaSecure auto-selects key from JWE header (don't override)

---

CRYPTO_005: Algorithm Not Supported

Symptom:

{
  "error": "CRYPTO_005",
  "message": "Algorithm not supported: INVALID-ALGO"
}

HTTP Status: 400 Bad Request

Solutions:

1. Verify algorithm name (case-sensitive):

   # ❌ WRONG
   --algorithm ml-kem-768  # Lowercase
   
   # ✅ CORRECT
   --algorithm ML-KEM-768  # Uppercase
   

2. List supported algorithms:

   ankasecure-cli key algorithms
   # Shows all 78 supported algorithms
   

See algorithm catalog →

---

Rate Limiting Errors

RATE_001: Rate Limit Exceeded

Symptom:

{
  "error": "RATE_001",
  "message": "Rate limit exceeded. Try again in 60 seconds.",
  "retryAfter": 60
}

HTTP Status: 429 Too Many Requests

Solutions:

1. Check rate limit headers:

   curl -I https://api.ankasecure.com/api/v1/crypto/encrypt \
     -H "Authorization: Bearer YOUR_TOKEN"
   
   # Response headers:
   # X-RateLimit-Limit: 60
   # X-RateLimit-Remaining: 0
   # X-RateLimit-Reset: 1735000000
   

2. Implement exponential backoff:

   # Wait specified time in Retry-After header
   sleep 60
   # Then retry
   

3. Reduce request rate: Add delays between operations

4. Upgrade tier: sales@ankatech.co for higher rate limits

---

Quota Errors

QUOTA_001: Monthly Quota Exceeded

Symptom:

{
  "error": "QUOTA_001",
  "message": "Monthly quota exceeded. Upgrade plan or wait for reset.",
  "quotaLimit": 100000,
  "quotaUsed": 100143,
  "resetDate": "2025-01-01T00:00:00Z"
}

HTTP Status: 402 Payment Required

Solutions:

1. Check quota usage:

   ankasecure-cli tenant quota
   
   # Output:
   # Operations Used: 100,143 / 100,000
   # Reset Date: 2025-01-01
   # Status: EXCEEDED
   

2. Optimize usage: Reduce unnecessary operations (cache results, batch requests)

3. Upgrade plan: sales@ankatech.co

---

Validation Errors

VALIDATION_001: Invalid Request Body

Symptom:

{
  "error": "VALIDATION_001",
  "message": "Invalid request body",
  "details": [
    {
      "field": "algorithm",
      "issue": "Must be one of: ML-KEM-512, ML-KEM-768, ML-KEM-1024",
      "received": "KYBER-768"
    }
  ]
}

HTTP Status: 400 Bad Request

Solutions:

1. Use official algorithm names:

   # ❌ WRONG: Old name
   --algorithm KYBER-768
   
   # ✅ CORRECT: NIST name
   --algorithm ML-KEM-768
   

2. Verify field names:

   {
     "keyId": "my-key",  // ✅ Correct: keyId
     "algorithm": "ML-KEM-768"
   }
   
   {
     "kid": "my-key",  // ❌ Wrong: Should be keyId
     "alg": "ML-KEM-768"  // ❌ Wrong: Should be algorithm
   }
   

---

File Size Errors

PAYLOAD_001: Payload Too Large

Symptom:

{
  "error": "PAYLOAD_001",
  "message": "Payload exceeds 5 MB limit. Use streaming API.",
  "payloadSize": 10485760,
  "maxSize": 5242880
}

HTTP Status: 413 Payload Too Large

Solutions:

Use streaming API for files >5 MB:

# ✅ CORRECT: Streaming for large files
ankasecure-cli stream-encrypt \
    --key-id my-key \
    --input large-file.bin \
    --output large-file.enc

# ❌ WRONG: Compact API for large files
ankasecure-cli encrypt \
    --key-id my-key \
    --input large-file.bin  # Fails if >5 MB

See streaming API documentation →

---

Getting Help

Before Contacting Support

Gather diagnostic information:

1. CLI version:

   ankasecure-cli version
   

2. Configuration:

   ankasecure-cli config show
   # (API key will be masked for security)
   

3. Error details:

4. Full error message
5. HTTP status code
6. Correlation/trace ID

7. Command executed

8. Network test:

   curl -I https://api.ankasecure.com/api/v1/public/health
   

---

Contact Support

Email: support@ankatech.co

Include: - CLI version - Error message (full JSON) - Trace ID / Correlation ID - Command executed (redact API key) - Operating system (Linux, macOS, Windows)

Response Time: - Free tier: 2-3 business days - Paid tiers: 1 business day (P1: 4 hours) - Enterprise: 4 hours (P1: 1 hour)

---

Related Resources

• API Error Guide - REST API error troubleshooting
• Error Catalog - Complete error code reference
• CLI Commands - Command reference
• SDK Troubleshooting - SDK-specific issues

---

Documentation Version: 3.0.0 Last Updated: 2025-12-26