Errors

Errors return JSON with a stable shape. Validation issues may include a param field.

{
  "error": {
    "type": "api_error",
    "code": "authentication_error",
    "message": "Human-readable detail",
    "param": null,
    "request_id": "req_…"
  }
}

HTTP status codes

Status	Code	Description
401	authentication_error	Missing or invalid Bearer API key.
422	validation_error	Request body failed schema or business validation.
413	payload_too_large	Request body or state exceeds size limits.
429	too_many_requests	Rate limit exceeded. Retry after Retry-After seconds.
503	model_warming	Inference worker is starting (strike-1). Retry with backoff.
529	engine_unavailable	Engine not ready or overloaded.
404	not_found	Resource not found (e.g. retention id).

413 — payload too large (proxy or API limits). 429 — rate limit; honor Retry-After. 503 with model_warming — cold start on strike-1; retry with backoff.