Skip to navigation
Platform

Errors and troubleshooting

Identify errors and decide when to retry.
View as Markdown

Error response

Failed HTTP requests return a non-2xx status with a JSON error:

{
  "error": {
    "code": "INVALID_SPEECH_REQUEST",
    "message": "The speech request is invalid",
    "requestId": "019c2e72-149f-733a-9579-67df595ba0f0"
  }
}
FieldUse
codeAn UPPER_SNAKE_CASE identifier for handling the error in your application.
messageRead the explanation; do not match its wording in code.
requestIdIdentify the request in logs or when contacting support. Matches x-request-id.

HTTP errors

These errors apply to HTTP requests and failed WebSocket handshakes.

HTTP statusError codeWhat to do
400WEBSOCKET_REQUIREDConnect to /v1/realtime?intent=transcription with a WebSocket client.
400INVALID_REQUESTFor an STT handshake, use intent=transcription.
400INVALID_VOICES_REQUESTProvide exactly one model query parameter when listing voices.
400INVALID_SPEECH_REQUESTUse documented fields and types, omit optional fields instead of sending null, and keep trimmed input within 1–2,048 characters. seed must be an integer from 0 through 4294967295.
400UNSUPPORTED_RESPONSE_FORMATUse wav or pcm.
400INVALID_VOICEUse an exact, case-sensitive voice ID from the selected model’s catalog.
400INVALID_VOICE_LANGUAGEOmit language, use auto, or match the selected voice’s language.
401INVALID_API_KEYCheck your API key and Authorization header.
402INSUFFICIENT_CREDITSAdd credits on the Billing page.
404MODEL_NOT_FOUNDUse a supported model ID.
413REQUEST_TOO_LARGEKeep the complete JSON request body within 65,536 bytes and reduce large field values if necessary.
429CONCURRENCY_LIMIT_EXCEEDEDWait for an in-flight request to finish before retrying.
429UPSTREAM_RATE_LIMITEDRetry with backoff.
500INTERNAL_ERRORRetry with backoff; contact support with the request ID if it persists.
503UPSTREAM_UNAVAILABLEThe inference service is unavailable or returned an unexpected response. Retry with backoff.
503SERVICE_UNAVAILABLE, AUTH_BACKEND_UNAVAILABLE, RATE_LIMIT_UNAVAILABLE, REQUEST_GATE_UNAVAILABLE, VOICE_CATALOG_UNAVAILABLE, USAGE_QUEUE_UNAVAILABLE, ENTITLEMENT_UNAVAILABLE, SERVER_NOT_READY, SERVER_AT_CAPACITY, SERVER_DRAININGRetry with backoff.

For transient failures, increase the delay between retries and add a small random delay to avoid simultaneous retries. Set a maximum retry count. See Rate limits for concurrency policies.

If the TTS quickstart request fails, rerun it without --fail and --output speech.wav to display the JSON error in your terminal.

WebSocket failures

After a successful handshake, WebSocket errors are sent as JSON before the close frame when possible. STT uses an error event:

{
  "type": "error",
  "event_id": "event_123",
  "error": {
    "code": "INVALID_REQUEST",
    "message": "First event must be session.configure",
    "requestId": "019c2e72-149f-733a-9579-67df595ba0f0"
  }
}

Use error.code to handle STT errors and error.requestId to find the connection in Request logs. The close code appears there as WS <code>.

STT close codes

WS close codeError codeWhat to do
1008INVALID_REQUESTCheck the session configuration and audio format.
1008SESSION_SETUP_TIMEOUTPrepare to send the configuration within 10 seconds of connecting.
1008MODEL_NOT_FOUNDChoose an active public STT model ID.
1008INSUFFICIENT_CREDITSAdd credits before reconnecting; see credit handling.
1008SESSION_CONFIGURATION_LOCKEDOpen a new connection to use different settings.
1008INVALID_API_KEYCheck whether the API key has expired or is otherwise invalid.
1008SESSION_IDLE_TIMEOUTReconnect when ready to send audio; see session limits.
1009MESSAGE_TOO_LARGEReduce the WebSocket message or audio chunk size.
1008, 1011, or 1013UPSTREAM_UNAVAILABLEIf setup failed, check the session arguments. Otherwise, retry with backoff.
1008 or 1011REQUEST_GATE_UNAVAILABLERetry with backoff.
1011VAD_OVERLOADED, VAD_UNAVAILABLE, VAD_RUNTIME_ERROR, INTERNAL_ERRORReconnect with backoff.
1012SERVER_DRAININGReconnect with backoff.

Invalid language, prompt, VAD settings, or unknown session fields can return UPSTREAM_UNAVAILABLE during setup. Check your session arguments before retrying.

Insufficient credits for STT

STT requires enough credit for the next 36 seconds of audio, but charges only for audio accepted. A positive balance may still be too low to continue.

On INSUFFICIENT_CREDITS, stop sending audio, keep completed transcripts, and add credits before reconnecting. The connection closes with code 1008. See Usage and billing for charging rules.

TTS input streaming errors

TTS uses a flat JSON error:

{"error":"invalid_request","message":"initial text must be a space","requestId":"019c2e72-149f-733a-9579-67df595ba0f0"}

Handle the string error field. Keep x-request-id from the handshake; some error messages omit requestId.

WS close codeExamples of error codesWhat to do
1008invalid_request, input_timeout, insufficient_creditsCorrect the input/options, reconnect when ready to send text, or add credits.
1009input_too_largeReduce input and message sizes.
1011timeout, backpressure, generation_failedConsume audio promptly; reconnect with backoff for transient failures.
1013service_unavailableRetry with backoff when the service is available.

See TTS input streaming for supported options.

Interrupted streams

TTS HTTP: Check the HTTP status before treating the body as audio. A failure after streaming starts can interrupt the audio without a JSON error. Treat a failed read as incomplete delivery. Retrying generates the full text again; there is no resume offset.

TTS input streaming: If the connection ends before isFinal: true, treat the audio as incomplete. Reconnect to start a new request; there is no resume offset. Check Request logs for completed segments before resending text, since resending them can incur another charge.

STT: Reconnect, authenticate, and send a new session configuration. Keep completed transcripts already received. If you retained the audio for unfinished utterances, you can resend it; it receives new IDs and is not automatically deduplicated. Only a received transcript.completed event confirms a final transcript.