Skip to main content
When a request fails, the API returns a non-2xx status code and a JSON body with a consistent envelope.

​
Error envelope

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable description of what went wrong."
  }
}
​
error.code
string
A stable, machine-readable code. Branch on this rather than on message.
​
error.message
string
A human-readable description of the failure. May change; not for branching.
​
error.details
array
Optional. Field-level validation details, each with a field and message, present on some VALIDATION_ERROR responses.
​
error.trace_id
string
Optional. An identifier for the failed request, included on server-side errors (5xx). Quote it when reporting an issue.

​
Status codes

StatusCodeMeaning
400VALIDATION_ERRORThe request body is invalid (for example, an empty prompt).
401UNAUTHORIZEDThe bearer token is missing, malformed, or expired.
502UPSTREAM_ERRORA dependency the request relies on was unavailable. Retry.
503DATABASE_ERRORThe request could not be completed. Retry after a short delay.

​
Handling errors

  • Always check the status code before reading a success body.
  • Branch on error.code, not on the human-readable error.message.
  • Retry 502 and 503 with backoff; do not retry 400 or 401 without fixing the request first.
resp = httpx.post(url, headers=headers, json=payload)
if resp.is_error:
    err = resp.json()["error"]
    raise RuntimeError(f"{err['code']}: {err['message']}")