Skip to main content

​
Error Response Format

When an API request fails, the QIMEM Platform returns a structured error response with an appropriate HTTP status code.

​
Standard Error Response

{
  "error": "detailed error message"
}
​
error
string
Human-readable error message describing what went wrong.

​
HTTP Status Codes

The API uses standard HTTP status codes to indicate the success or failure of requests:
Status CodeMeaningWhen Used
200 OKSuccessRequest completed successfully
400 Bad RequestClient ErrorInvalid input, validation failure, or unsupported operation
404 Not FoundResource Not FoundRequested key or resource does not exist
500 Internal Server ErrorServer ErrorUnexpected server-side error

​
Error Types

The platform defines several error types based on the QimemError enum:

​
Key Errors

​
KeyNotFound

HTTP Status: 404 Not Found Returned when a requested encryption key cannot be found in the key store. 
{
  "error": "key not found: 550e8400-e29b-41d4-a716-446655440000"
}
Common causes:
  • Invalid or non-existent key_id
  • Key was deleted or never created
  • Wrong key store or database connection

​
KeyInactive

HTTP Status: 400 Bad Request Returned when attempting to use an inactive (rotated or disabled) key for encryption. 
{
  "error": "key is inactive: 550e8400-e29b-41d4-a716-446655440000"
}
Resolution:
  • Use the active key in the lineage
  • Rotate to create a new active key version

​
Envelope Errors

​
UnsupportedVersion

HTTP Status: 400 Bad Request Returned when the envelope version is not supported by the platform. 
{
  "error": "unsupported envelope version: 2"
}
Common causes:
  • Corrupted envelope data
  • Envelope created by incompatible QIMEM version
  • Manual envelope modification

​
UnsupportedAlgorithm

HTTP Status: 400 Bad Request Returned when the encryption algorithm specified in the envelope is not recognized. 
{
  "error": "unsupported algorithm id: 99"
}
Supported algorithms:
  • 0 - AES-256-GCM (default)

​
InvalidEnvelope

HTTP Status: 400 Bad Request Returned when the envelope structure is malformed or cannot be parsed. 
{
  "error": "invalid envelope: invalid base64"
}
Common causes:
  • Malformed base64 encoding
  • Truncated or corrupted envelope data
  • Invalid binary format

​
Cryptographic Errors

​
Encryption

HTTP Status: 500 Internal Server Error Returned when encryption operation fails. 
{
  "error": "encryption failed"
}
Common causes:
  • Invalid key material
  • Cryptographic library error
  • System resource exhaustion

​
Decryption

HTTP Status: 500 Internal Server Error Returned when decryption operation fails or produces invalid output. 
{
  "error": "decryption failed"
}
Common causes:
  • Tampered envelope or ciphertext
  • Authentication tag verification failure
  • Wrong key used for decryption
  • Corrupted encrypted data

​
Data Errors

​
Serialization

HTTP Status: 400 Bad Request Returned when data cannot be serialized or deserialized. 
{
  "error": "serialization failed: invalid JSON structure"
}
Common causes:
  • Invalid JSON in request body
  • Missing required fields
  • Type mismatch in request parameters

​
Configuration Errors

​
Config

HTTP Status: 400 Bad Request Returned when there is a configuration or internal state error. 
{
  "error": "configuration failed: plugin lock poisoned"
}
Common causes:
  • Internal concurrency issue
  • Invalid server configuration
  • Resource initialization failure

​
Database Errors

​
Database

HTTP Status: 500 Internal Server Error (Only available with stateful feature enabled) Returned when a database operation fails. 
{
  "error": "database error: connection timeout"
}
Common causes:
  • Database connection failure
  • Query timeout
  • Constraint violation
  • Transaction conflict

​
Example Error Scenarios

​
Encrypting with Non-Existent Key

Request: 
curl -X POST https://api.qimem.io/v1/security/encrypt \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "key_id": "00000000-0000-0000-0000-000000000000",
    "input": "secret data"
  }'
Response: 404 Not Found 
{
  "error": "key not found: 00000000-0000-0000-0000-000000000000"
}

​
Decrypting Invalid Base64

Request: 
curl -X POST https://api.qimem.io/v1/security/decrypt \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "input": "not-valid-base64!!!"
  }'
Response: 400 Bad Request 
{
  "error": "invalid envelope: invalid base64"
}

​
Using Inactive Key for Encryption

Request: 
curl -X POST https://api.qimem.io/v1/security/encrypt \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "key_id": "550e8400-e29b-41d4-a716-446655440000",
    "input": "secret data"
  }'
Response: 400 Bad Request 
{
  "error": "key is inactive: 550e8400-e29b-41d4-a716-446655440000"
}

​
Error Handling Best Practices

Check Status Codes

Always inspect HTTP status codes before parsing response bodies.

Retry Logic

Implement exponential backoff for 500 errors. Never retry 400 or 404 errors.

Log Error Messages

Log the full error message for debugging and monitoring.

User-Friendly Messages

Translate technical errors into user-friendly messages in your application.

​
Debugging Tips

1

Verify Authentication

Ensure your access token is valid and not expired using /v1/auth/token/introspect.
2

Check Request Format

Validate that your JSON request body matches the expected schema.
3

Confirm Resource Exists

For 404 errors, verify the resource ID exists before retrying.
4

Review Envelope Format

For decryption errors, ensure the envelope is properly base64-encoded and not corrupted.

Build docs developers (and LLMs) love

Get started for freeTalk to us