Errors, rate limits, and retries
AffixIO returns JSON error bodies with an error code and human-readable message. Use this reference for production integrations and OpenAPI client generation.
Rate limits
Production API keys are limited to 10 requests per second per key. When exceeded, the API returns HTTP 429:
{
"error": "rate_limited",
"message": "Maximum 10 requests per second per key."
}
Use exponential backoff with jitter. Batch eligibility checks on your side where possible. Enterprise orders may specify higher throughput.
Error catalogue
| HTTP | error | Meaning | Action |
|---|---|---|---|
| 401 | unauthorized | Missing or invalid API key | Check Bearer or X-API-Key header |
| 403 | demo_key_exhausted | Demo key quota used | Request production or partnership key |
| 429 | rate_limited | More than 10 req/s per key | Backoff and retry |
| 400 | invalid_request | Schema validation failed | Fix body against OpenAPI |
| 400 | invalid_digest | Merkle digest not 64 hex chars | Pass sha256 proof_digest |
| 404 | not_in_tree | Digest not in audit Merkle tree | Confirm digest and tree root time |
| 404 | not_found | Unknown route | Check path and API version |
| 503 | circuit_unavailable | Prover or circuit not ready | Retry; check status |
| 500 | prove_failed / verify_failed | Internal prove or verify error | Retry with idempotency key; contact support if persistent |
| 400 | double_spend_detected | Ticket or proof already spent | Expected for spent-proof enforcement |
Idempotency
Verify endpoints are safe to retry on network failure if your downstream enforcement checks proof_id or proof_digest uniqueness. Do not retry 400 validation errors without changing inputs. Log X-Demo-Key-Remaining on demo keys.
FAQ
Does health check count against rate limits?
GET /api/health is public and not authenticated; it does not consume API key quota.
Where is the OpenAPI error schema?
See openapi.json components and Postman collection.