Errors

Error response format

All errors return a consistent JSON structure:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The 'text' field is required",
    "status": 422,
    "details": {
      "field": "text",
      "constraint": "required"
    },
    "request_id": "req_abc123def456"
  }
}

HTTP status codes

400 Bad Request

401 Unauthorized

from engramma_cloud import EngrammaClient, AuthenticationError

try:
    client = EngrammaClient(api_key="invalid_key")
    client.stats()
except AuthenticationError as e:
    print(f"Auth failed: {e.code}")  # "INVALID_API_KEY"
    print(f"Message: {e.message}")

403 Forbidden

404 Not Found

409 Conflict

422 Unprocessable Entity

429 Too Many Requests

Rate limit headers on 429 responses:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 50
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1705312800
Retry-After: 3

from engramma_cloud import EngrammaClient, RateLimitError
import time

client = EngrammaClient(api_key=os.environ["ENGRAMMA_API_KEY"])

try:
    result = client.retrieve("query")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
    time.sleep(e.retry_after)
    result = client.retrieve("query")  # Retry

# The SDK handles retries automatically by default

500 Internal Server Error

Retry strategy

The SDKs implement automatic retries with exponential backoff:

Never retry:

• 400 (bad request — fix the input)
• 401 (auth failed — fix credentials)
• 403 (forbidden — fix permissions)
• 404 (not found — resource doesn't exist)
• 409 (conflict — resolve the conflict)
• 422 (validation — fix the data)

# Configure retry behavior
client = EngrammaClient(
    api_key=os.environ["ENGRAMMA_API_KEY"],
    max_retries=3,           # Default: 3
    retry_delay=1.0,         # Base delay in seconds
    retry_backoff=2.0        # Exponential backoff multiplier
)

Error handling best practices

1. Always check error.code — not just the HTTP status. Multiple error types share the same status code.

2. Log the request_id — include it in support tickets for fast debugging.

3. Handle rate limits gracefully — the Retry-After header tells you exactly how long to wait.

4. Don't retry client errors — 4xx errors (except 429) won't succeed on retry.

5. Use SDK error classes — they provide typed access to error details.

Next steps

• API Overview — Base URL, auth, rate limits
• Memory Core — Core memory endpoints
• SDKs — Error handling built into the SDKs