> ## Documentation Index
> Fetch the complete documentation index at: https://plivo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Text-to-Speech Errors and Close Codes

> HTTP error codes, WebSocket error events and close codes for the Plivo Text-to-Speech API.

> [!NOTE]
>
> What each Text-to-Speech error code means, whether to retry, and how to fix it, for both REST and the WebSocket.

## Error format

**HTTP** (including a refused WebSocket upgrade):

```json theme={null}
{"api_id": "...", "error": "...", "code": "voice_not_found", "param": "voice_id"}
```

`param` is present only when one field is at fault. `api_id` equals the `connection-id` reply header. A `401` also carries `WWW-Authenticate: Basic realm="plivo"`.

**On an open WebSocket**, an `error` event:

```json theme={null}
{"type": "error", "code": "...", "message": "...", "param": "...", "context_id": "...", "connection_id": "..."}
```

## Error codes

"Retry" means the reply has `Retry-After: 1`. Wait 1 second and retry.

| Code | HTTP | Retry | Meaning | Fix |
| - | - | - | - | - |
| `invalid_request` | 422 (400 body not a JSON object, 413 over 1 MiB, 408 slow upload) | No | A field is wrong. `param` names it. | Fix the field. Leave out fields instead of sending `null`. |
| `unauthorized` | 401 | No | Bad or missing credentials | Check Auth ID and Auth Token |
| `insufficient_balance` | 400 | No | Insufficient credits in the account | Add credits in the [console](https://cx.plivo.com/) |
| `forbidden` | 403 | No | The credentials don't belong to the account in the URL path | Use the Auth ID and Auth Token of the account in `/v1/Account/{auth_id}/` |
| `usage_limit_exceeded` | 403 | No | The account has reached its configured monthly usage limit | Increase the limit in [account settings](https://cx.plivo.com/account-settings) or contact your account manager |
| `voice_not_found` | 404 | No | Unknown voice, or one you may not use | List voices and use a returned `voice_id` |
| `language_not_supported` | 400 | No | The voice doesn't speak that language | Pick a voice for the language |
| `empty_text` | 400 | No | Nothing to speak | Send non-empty `text` |
| `text_too_long` | 400 | No | Text over 5,000 characters | Split the text |
| `unsupported_format` | 400 | No | Output format not offered | See [Output format](https://plivo.com/docs/models/text-to-speech/api/batch.md#output-format) |
| `not_found` | 404 | No | Unknown route or lexicon | Check the URL or `lexicon_id` |
| `method_not_allowed` | 405 | No | Wrong HTTP method | |
| `concurrency_limit` | 429 | Yes | Account at 50 open connections | Reuse sockets. Close idle ones. |
| `auth_unavailable` | 503 | Yes | Account service failed | Retry |
| `at_capacity` | 503 | Yes | No capacity right now | Retry |
| `draining` | 503 | Yes | Server not taking new work | Retry |
| `backend_error` | 502 | Yes | Backend failed | Retry |
| `internal_error` | 500 | No | Server fault | Contact support with the `api_id` |
| `cancelled` | 499 | No | You canceled, or the client left | |

A plain `GET` on the [Realtime](https://plivo.com/docs/models/text-to-speech/api/realtime.md) URL without a WebSocket upgrade returns HTTP `426` with `Upgrade: websocket`. That's a status, not an error code: connect with a WebSocket client.

## WebSocket close codes

| Code | When | What to do |
| - | - | - |
| 1013 | Retryable error | Reconnect |
| 1011 | Server (5xx) error | Reconnect with backoff |
| 1008 | Other errors | Read the last `error` event |

## Common problems

### WAV file shows a huge duration

### Audio sounds like noise on a phone call

The output format doesn't match the call. Use `pcm_mulaw` at `8000` Hz for Plivo calls.

## Get help

Contact [Plivo Support](https://support.plivo.com) with the `api_id` or `connection_id`.
