Errors and limits
Handle retries, quotas, rate limits, timeouts, and failed jobs.
All request failures use a stable JSON envelope. Answer-job failures are represented in the job body instead of an error HTTP status.
Error envelope
{
"detail": {
"code": "rate_limit_exceeded",
"message": "Per-minute rate limit exceeded for your plan."
}
}FastAPI validation failures return HTTP 422 with field-level validation details. Treat them as permanent request errors.
Retry policy
| HTTP | Example code | Retry? | Recommended handling |
|---|---|---|---|
401 | invalid_api_key | No | Replace or correct the key. |
403 | key_limit_reached | No | Revoke a key or change the account tier. |
404 | document_not_found | No | Verify the identifier pair came from search. |
422 | invalid_request | No | Correct request fields or filter combinations. |
429 | rate_limit_exceeded | Yes | Honor Retry-After and add jitter. |
429 | monthly_quota_exceeded | No | Stop the workload until quota is available. |
429 | overage_limit_exceeded | No | Raise the account's overage cap or wait for the next UTC month. |
503 | quota_service_unavailable | Yes | Retry after the indicated delay with backoff. |
500 | search_failed | Cautiously | The unit is refunded; retry with a bounded policy. |
Use exponential backoff with jitter and a small retry budget. Never retry 401, 403, 404, or 422 unchanged.
Per-minute limits
Every API-key endpoint is rate-limited. A successful response includes X-RateLimit-Limit. When the current worker rejects a request, the API returns Retry-After in seconds.
The beta limiter is maintained per worker, so the effective global ceiling can be higher than the published tier limit. Do not depend on that implementation detail; shape traffic to the advertised value.
Monthly quota
Searches, document retrievals, and answers have separate monthly counters pooled across every API key in the account. GET /v1/usage reports current UTC-month consumption, limits, and estimated overage spend.
Quota is consumed atomically before expensive work starts. Search, retrieval, and answer failures refund their unit. If metering is unavailable, the API fails closed with 503 instead of running unmetered work.
Paid overages are disabled by default. Eligible Launch and Scale customers can enable them and set a monthly EUR spending cap in API access. Only successful units beyond the included allowance are sent to Stripe; an operation that fails is neither counted nor billed.
Timeouts and duplicate work
- Allow at least 60 seconds for synchronous search.
- Poll answer jobs rather than holding a request open.
- A timed-out answer job is failed and refunded after 15 minutes.
- The beta API does not yet accept idempotency keys. If a client loses the response after a request was accepted, an automatic retry can create duplicate work.
For batch integrations, record your own correlation ID with the returned job_id, cap concurrency, and compare usage before and after the run.