Error Reference

All errors return a JSON body with an error field containing a human-readable message. Some structured errors include a code field for programmatic handling.

Error body format

{
  "error": "Human-readable error message",
  "code": "MACHINE_CODE (optional, included for structured errors)"
}

HTTP status codes

Code	Name	When it occurs
400	Bad Request	A required field is missing or a value is invalid (e.g. missing title on POST /v1/conversations).
401	Unauthorized	No x-api-key header was provided, or the key could not be found.
402	Payment Required	Insufficient token balance to complete an AI-heavy operation (debate, advance simulation, generate risk tree).
403	Forbidden	The API key does not have the required scope for this endpoint (e.g. calling /v1/agents without the "agents" scope).
404	Not Found	The requested resource does not exist or does not belong to your workspace.
429	Too Many Requests	Rate limit exceeded. See Rate Limits for per-key limits.
500	Internal Server Error	An unexpected server error occurred. Retry with exponential backoff.

Structured error codes

Some 402 errors include extra context to help handle free-tier limits:

{
  "error": "Free tier limit reached for simulations",
  "code": "FREE_TIER_LIMIT",
  "feature": "simulations",
  "limit": 3,
  "used": 3
}

Retry guidance

4xx errors — do not retry automatically; fix the request first.
500 errors — safe to retry with exponential backoff (1s → 2s → 4s).
429 errors — honour the Retry-After header if present, otherwise back off 10–30 seconds.