Idempotency & Retries

Network issues and timeouts happen. The API is designed so retrying a request is always safe when you follow the guidance below.

Idempotency keys

Pass an Idempotency-Key header (any unique string, e.g. a UUID) with any mutating request. If you retry the same request with the same key within the 24-hour cache TTL, the API returns the original cached response instead of executing the call again — so a client-side retry after a timeout never double-executes or double-bills a call.

curl https://<base-url>/v1/documents/analyze \
  -H "Authorization: Bearer cai_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f14e45f-ceea-4c9d-b1c6-example" \
  -d '{"document_text": "..."}'

Automatic retries

Every /v1 handler already degrades gracefully instead of hard-failing when the underlying model call errors. On top of that, transient upstream errors (429/529/timeout from the model provider) are retried server-side with exponential backoff before falling back to a degraded response — you should still implement client-side retries with backoff for your own network-level failures.

Recommended client retry policy

• Retry on 429 and 5xx, and on connection/timeout errors.
• Do not retry on 400, 401, or 403 — fix the request instead.
• Use exponential backoff with jitter (e.g. 1s, 2s, 4s, capped at 3 attempts).
• Always send the same Idempotency-Key across retries of the same logical request.