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

# Error Codes & Troubleshooting

> Authentication, WebSocket, and pronunciation-dictionary error codes for the SLNG API, plus fixes for common streaming and audio-format issues.

## Authentication errors

| Error                            | Cause                                | Fix                                                                                                                      |
| -------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| HTTP 401                         | Missing or invalid SLNG key          | Check the `Authorization: Bearer SLNG_API_KEY` header. Verify the key is active in the [Dashboard](https://app.slng.ai). |
| WebSocket rejected with 401      | SLNG key not passed in the handshake | Pass the key as a header (`Authorization: Bearer SLNG_API_KEY`) or query parameter (`?token=SLNG_API_KEY`).              |
| `X-Slng-Auth-Source: client_key` | BYOK provider key rejected upstream  | Your provider key was rejected, not the SLNG key. Check the key with the provider directly.                              |

## WebSocket errors

| Error code                  | Meaning                             | What to do                                                         |
| --------------------------- | ----------------------------------- | ------------------------------------------------------------------ |
| `auth_error`                | Invalid or missing SLNG key         | Check your Authorization header.                                   |
| `config_error`              | Invalid session configuration       | Verify your `init` message parameters.                             |
| `rate_limit`                | Too many concurrent connections     | Back off and retry with exponential delay.                         |
| `provider_error`            | Upstream model returned an error    | Check model availability; consider configuring failover models.    |
| `backend_connection_failed` | Could not connect to upstream model | The model may be temporarily unavailable; retry or use a fallback. |

## Pronunciation dictionary errors

| Status | Code                            | Meaning                                                                   |
| ------ | ------------------------------- | ------------------------------------------------------------------------- |
| 400    | `invalid_pronunciation`         | Malformed object, invalid name, unsupported mode, or dictionary not found |
| 401    | `pronunciation_unauthenticated` | Missing or unresolved organization context                                |
| 409    | `pronunciation_conflict`        | Dictionary name already exists in your organization                       |
| 503    | `pronunciation_unavailable`     | Platform dependency failure during dictionary resolution                  |

WebSocket pronunciation errors return an error frame:

```json theme={null}
{
  "type": "error",
  "code": "pronunciation_not_found",
  "message": "Pronunciation dictionary not found: support-pronunciations"
}
```

## Common issues

### Connection drops

WebSocket disconnects unexpectedly.

* Implement reconnection with exponential backoff (1s, 2s, 4s, up to 30s).
* Send periodic keep-alive messages (`{"type": "keepalive"}` for STT) to prevent idle timeouts.
* If behind a corporate proxy, confirm it supports WebSocket upgrades (the `Connection: Upgrade` header).

### Choppy or distorted audio (TTS)

* Buffer at least 200ms of audio before starting playback.
* Use the WebAudio API (`AudioContext`) instead of `<audio>` elements for gapless chunk playback.
* Confirm your player's sample rate matches the `sample_rate` from your `init` config.
* 24kHz linear16 audio requires roughly 384 kbps. Verify your connection can sustain it.

### Delayed transcriptions (STT)

* Send audio in 20-100ms chunks (320-1600 bytes at 16kHz linear16).
* Confirm `encoding` and `sample_rate` in your `init` config match your actual audio format.
* For real-time use, prefer Deepgram Nova, which is optimized for streaming latency.

### Audio format mismatch

Keep your audio configuration consistent across the pipeline:

```json theme={null}
{
  "encoding": "linear16",
  "sample_rate": 16000
}
```

Your audio capture must match: 16-bit samples, 16000 Hz, single channel (mono).

## Getting help

* Email: [support@slng.ai](mailto:support@slng.ai)
* Discord: [discord.gg/slng](https://discord.gg/slng)