Errors

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

Status	Code	Meaning
`400`	`VALIDATION_ERROR`	The request body is invalid (for example, an empty `messages`).
`401`	`UNAUTHORIZED`	The bearer token is missing, malformed, or expired.
`402`	`PAYMENT_REQUIRED`	Your credit balance can’t cover the request. See Credits and billing.
`403`	`forbidden`	The credentials are valid but not permitted for this endpoint.
`502`	`UPSTREAM_ERROR`	A dependency the request relies on was unavailable. Retry.

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 with backoff; do not retry 400, 401, or 402 without fixing the request first (top up your credit balance to clear a 402).

resp = httpx.post(url, headers=headers, json=payload)
if resp.is_error:
    err = resp.json()["error"]
    raise RuntimeError(f"{err['code']}: {err['message']}")

Get started

Turn-taking API

Persona API

Social Learning API

Social Observability API

Social Memory API

Theory of Mind API

Account

Error envelope

Status codes

Handling errors

​Error envelope

​Status codes

​Handling errors

Error envelope

Status codes

Handling errors