Errors and retries

Errors use a consistent JSON shape:

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed"
  }
}

Use error.code in application logic. Every response also includes x-request-id; log it and include it when contacting support.

Common responses

HTTP	Meaning	Retry?
401	Missing, invalid, or revoked key	No
403	Tenant suspended	No
404	Index or document not found	No
422	Invalid request or document limit reached	No
429	Rate, concurrency, or monthly usage limit	Usually; inspect `error.code`
500, 502, 503, 504	Temporary service failure	Yes, with a limit

Retry temporary network failures and the retryable statuses above with exponential backoff and jitter. Honor Retry-After when present. Stop after a small number of attempts; six total attempts is a reasonable upper bound. Do not keep retrying usage_limit_exceeded. Wait for the allowance to reset or contact support.

Safe retries

Document upserts are safe to repeat because doc_id replaces existing content. Still inspect failed after every HTTP 200.
Document deletion, list, usage, search, and score requests are safe to repeat.
Index creation is not safely repeatable. After a timeout, list indexes and check for the intended name before trying again.

Set finite client timeouts. A timeout does not prove that the server abandoned the request.

Get started

Guides

Help

Common responses

Safe retries

​Common responses

​Safe retries

Common responses

Safe retries