Errors

The error envelope

Application-level errors (bad requests, auth failures, missing resources, rate limits) are returned as JSON with a non-2xx status code, in a consistent envelope:

{
  "error": {
    "type": "invalid_request_error",
    "code": "avatar_not_found",
    "message": "No avatar with id 'avt_doesnotexist' was found.",
    "request_id": "req_5f3a1c9e2b7d"
  }
}

Field	Description
type	Broad error category. Stable, safe to branch on in code.
code	Specific machine-readable reason within that category.
message	Human-readable explanation. Don’t parse this; it can change wording without notice.
request_id	Unique ID for this request. Include it when contacting support.

Always branch on HTTP status code and error.type (and error.code where you need finer granularity), never on the exact text of message.

Common error types

HTTP status	error.type	Typical error.code	Meaning
400	invalid_request_error	avatar_not_found, missing_field	The request was malformed or referenced something that doesn’t exist.
401	authentication_error	invalid_api_key, missing_api_key	The Authorization header was missing or the key was invalid.
403	permission_error	key_revoked	The key is valid but not allowed to perform this action.
404	not_found_error	session_not_found	The path referenced a resource (session, voice) that doesn’t exist or isn’t yours.
409	conflict_error	session_already_ended	The request conflicts with the resource’s current state.
429	rate_limit_error	concurrent_session_limit_exceeded	You’re over your concurrency limit. See Limits & concurrency.
500	api_error	(none)	Something went wrong on our end. Safe to retry with backoff.

Note

This table is representative, not exhaustive. New code values may be added over time as the API grows. Code defensively: handle unrecognized code values within a known type the same way you’d handle the type generically.

Validation errors are a different shape

One exception to the envelope above: 422 responses for malformed request bodies (missing required fields, wrong types) come from automatic request validation and use a different, framework-standard shape:

{
  "detail": [
    {
      "loc": ["body", "avatar_id"],
      "msg": "field required",
      "type": "missing"
    }
  ]
}

If you get a 422, check detail (an array of field-level issues) rather than error. Every other status code uses the error envelope above.

Next

• Limits & concurrency for the specific case of 429s.