Errors

Error categories and handling guidance for OptimAI Search API consumers.

Handle errors by category, not only by message text. The server may include a machine-readable code, details, and request ID; preserve those fields for support and retry decisions.

Error envelope

{
  "error": {
    "code": "invalid_request",
    "message": "The request body is invalid.",
    "details": {}
  },
  "request_id": "req_123"
}

The exact server code strings can evolve. Prefer the HTTP status, returned message, and top-level request ID instead of hard-coding an undocumented code enum.

Status	Meaning	Action
`400`	Invalid request shape	Fix the payload.
`401`	Missing or invalid key	Check authentication.
`402`	Payment or credit required	Ask the user to add credits or payment.
`404`	Operation not found or not accessible	Check the operation ID and API key.
`429`	Rate limited	Back off and retry later.
`500`	Server-side error	Preserve the request ID and retry only when safe.
`502`/`503`/other `5xx`	Temporary service issue	Retry with backoff if safe.

Preserve context

Log the status code, endpoint, and top-level request_id when available. Keep the request ID with the error message when opening a support ticket.