Errors
Errors from the REST API are an ErrorResponse: { "error": { "code", "message", "request_id", "details" } }. On the realtime connection an error event carries the same code, with fatal and retryable flags. Quote the request_id when you report a problem.
Error codes
Section titled “Error codes”| Code | Meaning | REST (/v1) | Realtime |
|---|---|---|---|
invalid_request |
Fix the request. | yes | yes |
invalid_audio |
A malformed audio frame; the frame is dropped. | no | yes |
unauthenticated |
Missing or invalid API key or client secret. | yes | yes |
secret_expired |
The client secret is older than 60 s or already used: create a new session. | yes | yes |
forbidden |
The key lacks the scope, or the partner is suspended. | yes | yes |
origin_not_allowed |
The web origin isn’t allowed for this partner. | yes | yes |
voice_not_found |
Unknown or retired voice, or not enabled for this partner. | yes | yes |
session_not_found |
No such session. | yes | yes |
capacity_exhausted |
The whole service is full; retry after the hinted seconds. | yes | yes |
partner_limit_reached |
The partner is at its maximum concurrent sessions. | yes | yes |
rate_limited |
Too many API calls. | yes | yes |
provider_unavailable |
A processing step failed. Non-fatal for one turn; fatal after 3 failures in a row. | no | yes |
internal |
Our bug; the request ID finds it. | yes | yes |
not_found |
The resource doesn’t exist, or isn’t visible to your API key (a resource that belongs to someone else is not_found, so its existence isn’t revealed). |
yes | no |
conflict |
The request conflicts with the current state of the resource; change the request and retry. | yes | no |
unavailable |
The API is temporarily unavailable; retry later. | yes | no |
The error object
Section titled “The error object”One error: a stable code, a short message and the request ID.
| Field | Type | Required | Description | Rules |
|---|---|---|---|---|
code |
string | yes | One of the codes above. | |
message |
string | yes | A short, fixed description. Never quotes the request. | |
request_id |
string | yes | The request’s ID (also in the X-Request-Id header); quote it when reporting a problem. |
pattern ^req_[0-9A-HJKMNP-TV-Z]{26}$ |
details |
any | no | Structured detail, e.g. {"field": "languages[1]"} or {"reason": "quota_exhausted"}. |