Errors and retries

Errors use the same envelope shape as successful responses:

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The request could not be validated."
  },
  "meta": {
    "request_id": "req_example_12345"
  }
}

Error classes

Status	Representative codes	Action
`401`	`MISSING_API_KEY`, `INVALID_API_KEY`, `DISABLED_API_KEY`, `REVOKED_API_KEY`	Fix or replace the credential; do not retry unchanged.
`402`	`INSUFFICIENT_CREDITS`	Wait for the free reset or add shared credits.
`403`	`FORBIDDEN`, `USER_SUSPENDED`, `FEATURE_DISABLED`	Check scopes and account access; do not retry unchanged.
`404`	`NOT_FOUND`	Re-resolve the identity or stop. Gated operations can also return a neutral not-found response.
`422`	`INVALID_REQUEST`	Correct fields, filters, or identifiers.
`429`	`RATE_LIMITED`	Wait for `Retry-After` or the rate-limit reset time.
`500`	`INTERNAL_ERROR`, `CONFIGURATION_ERROR`, `DATA_UNAVAILABLE`	Retry only transient failures with bounded backoff.

Retry policy

Retry idempotent GET requests and a search POST only when the failure is transient. Use exponential backoff with jitter, honor Retry-After, cap the number of attempts, and keep an overall deadline. Do not retry 401, 402, 403, 404, or 422 without changing the underlying condition. Record meta.request_id or x-qoory-request-id with the operation, timestamp, and status. Never include the bearer secret in a support report.

Overview

Get started

REST API guides

Data models

Agent integrations

Resources

API Reference

Error classes

Retry policy

​Error classes

​Retry policy

Error classes

Retry policy