ok: false and a machine-readable code.
Error envelope
Realtime WebSocket error frames
The realtime text-to-speech WebSocket reports errors as JSONerror frames instead of HTTP responses. The frame carries the same machine-readable code values as the table below; the human-readable text is in message (the WebSocket counterpart of the HTTP envelope’s detail), and optional context is in meta:
Status column shows each code’s default HTTP status; on the WebSocket the code arrives in an error frame, optionally followed by a close. Whether an error closes the session — and with which close code — is defined in the realtime guide.
Capacity refusals
Inference capacity refusals return HTTP429 with GENERATION_CAPACITY_EXCEEDED. Account concurrency limits use 429 with GENERATION_CONCURRENCY_EXCEEDED. A service-unavailable response remains 503; shared processing capacity can also return 503 with GENERATION_CAPACITY_EXCEEDED.
Generation requests are not automatically replayed. An optional Retry-After header describes when you may explicitly start another request. Python and TypeScript SDKs classify capacity 429 responses as rate-limit errors and capacity 503 responses as service-unavailable errors. Keep the code when deciding how to display the failure.
An accepted asynchronous job reports failure through its job status and error code; polling the job still returns a successful HTTP response. An audio stream can return 429 before audio starts. After the HTTP response starts, failure terminates the stream. Realtime capacity errors cancel the affected turn and keep the session available for a new, explicit turn.
Reference
Operational guidance
Authentication
Send API keys correctly and distinguish session-only account endpoints from API-key endpoints.
Rate limits
Retry concurrency, capacity, and timeout errors without overloading generation.
CLI troubleshooting
Map CLI exit codes to auth, quota, timeout, network, and dependency fixes.
Developer logs
Inspect failed requests, latency, request IDs, and generated cURL examples.

