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:

1{
2  "error": {
3    "code": "INVALID_REQUEST",
4    "message": "The speech request is invalid",
5    "requestId": "019c2e72-149f-733a-9579-67df595ba0f0"
6  }
7}
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.

StatusCodeWhat to do
400INVALID_REQUESTCorrect the fields described in message.
401INVALID_API_KEYCheck your API key and Authorization header.
402INSUFFICIENT_CREDITSAdd credits or use a Free model.
403PARTNER_ACCESS_REQUIREDRequest Partner access or use a Free model.
404MODEL_NOT_FOUNDUse a supported model ID.
413REQUEST_TOO_LARGEReduce the complete JSON body to at most 65,536 bytes.
429CONCURRENCY_LIMIT_EXCEEDEDWait for an in-flight request to finish before retrying.
429FREE_DAILY_LIMIT_EXCEEDEDWait until 00:00 UTC, or use a Partner model if you have early access and credits.
429UPSTREAM_RATE_LIMITEDRetry with backoff.
500INTERNAL_ERRORRetry with backoff; contact support with the request ID if it persists.
503SERVICE_UNAVAILABLE, AUTH_BACKEND_UNAVAILABLE, RATE_LIMIT_UNAVAILABLE, REQUEST_GATE_UNAVAILABLE, UPSTREAM_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 Free tier and rate limits for allowance and 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, STT reports errors as an error event before closing the connection:

1{
2  "type": "error",
3  "event_id": "event_123",
4  "error": {
5    "code": "EXPECTED_SESSION_CONFIGURE",
6    "message": "the first client event must be session.configure",
7    "requestId": "019c2e72-149f-733a-9579-67df595ba0f0"
8  }
9}

Use error.code to identify the cause. error.requestId matches the handshake’s x-request-id.

CodeWhat to do before reconnecting
EXPECTED_SESSION_CONFIGURESend session.configure as the first client event.
SESSION_SETUP_TIMEOUTPrepare to send the configuration within 10 seconds of connecting.
SESSION_CONFIGURATION_LOCKEDOpen a new connection to use different settings.
UNSUPPORTED_LANGUAGEChoose a supported language from the session reference, or omit it for automatic recognition.
INVALID_AUDIO, EMPTY_AUDIOSend nonempty base64 audio containing a whole number of PCM16 samples.
AUDIO_CHUNK_TOO_LARGE, JSON_TOO_LARGESplit audio into smaller append events. See audio input limits.
INVALID_FRAME, INVALID_JSON, INVALID_EVENTSend a JSON object in a text frame.
INVALID_REQUESTInclude session.model and correct the fields described in message. Unknown session fields are rejected.
UNSUPPORTED_EVENTUse a supported client event from the API reference.
UNSUPPORTED_TURN_DETECTION, INVALID_TURN_DETECTIONUse the supported VAD settings.
MODEL_NOT_SERVEDCheck the selected model; contact support if a supported model is rejected.
SESSION_IDLE_TIMEOUTReconnect when ready to send audio. The idle limit is 60 seconds without nonempty audio; waiting for a final result is exempt.
VAD_OVERLOADED, VAD_UNAVAILABLE, VAD_RUNTIME_ERROR, SERVER_DRAINING, INTERNAL_ERRORReconnect with backoff.

Network failures may close the connection without an error event. In that case, inspect the close code.

CodeMeaning and action
1000Normal closure.
1006Abnormal closure observed by the client; reconnect if needed. The server does not send this code.
1008Invalid input or a session timeout; inspect the error event before reconnecting.
1009Message too large; reduce chunk size.
1011Server failure; reconnect with backoff.
1012 / 1013Restart or temporary unavailability; reconnect with backoff.

Interrupted streams

TTS: 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.

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.