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

# Troubleshooting

> Common errors organized by category, with causes and fixes — auth, rate limits, audio validation, timeouts, and server errors.

Common errors organized by category, with causes and fixes.

## Authentication errors

### `401 Unauthorized`

**Cause:** No `X-API-Key` header was sent, or the header name is wrong.

**Fix:** Add the header to your request:

```bash theme={null}
curl -H "X-API-Key: your_api_key_here" ...
```

Double-check the exact casing — `X-API-Key`, not `x-api-key` or `Authorization`.

### `403 Forbidden` (REST)

Three different problems return `403`:

| Scenario                                    | Response detail                      | Fix                                                                                                                                                                                            |
| ------------------------------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Monthly Usage Quota exceeded (single model) | `"monthly limit reached"` or similar | Check your [Usage Dashboard](https://platform.modulate.ai/dashboard/usage). This per-model quota is set by Modulate — submit the [support form](/support#contact-us) to request a higher quota |
| Monthly Credit Limit reached (all models)   | `"monthly limit reached"` or similar | If your org set a Monthly Credit Limit, an admin can review or raise it in [Organization settings](https://platform.modulate.ai/dashboard/organization)                                        |
| Model not enabled for your org              | `"model access not enabled"`         | Check [the limits specified for your API key](https://platform.modulate.ai/dashboard/api-keys); otherwise contact [support@modulate.ai](mailto:support@modulate.ai)                            |

### WebSocket close code `4001` (Multilingual Transcription streaming)

**Cause:** The `api_key` query parameter is missing or contains an invalid key.

**Fix:** Pass the key at connection time:

```text theme={null}
wss://platform.modulate.ai/api/velma-2-stt-streaming?api_key=your_api_key_here
```

### WebSocket close code `4003`

**Cause:** Authentication succeeded but the model is not enabled for your organization.

**Fix:** Check [the limits specified for your API key](https://platform.modulate.ai/dashboard/api-keys); otherwise contact [support@modulate.ai](mailto:support@modulate.ai).

## Rate limit errors

### `429 Too Many Requests` (REST)

**Cause:** You've exceeded the concurrent request limit for that model.

**Fix:** Implement exponential backoff with jitter and retry:

```python theme={null}
import time, random, httpx

def post_with_retry(url, files, headers, max_retries=5):
    for attempt in range(max_retries):
        response = httpx.post(url, files=files, headers=headers)
        if response.status_code != 429:
            return response
        wait = (2 ** attempt) + random.uniform(0, 1)
        time.sleep(wait)
    return response
```

If you hit `429` consistently, review your concurrency patterns or request a higher limit for the model from the [Concurrency Limits page](https://platform.modulate.ai/dashboard/concurrency-limits) — see [Rate limits](/guides/authentication#rate-limits).

### WebSocket close code `4029`

**Cause:** Rate limit exceeded at WebSocket handshake — a monthly limit is full or the concurrency limit is hit.

**Fix:** Check your [Usage Dashboard](https://platform.modulate.ai/dashboard/usage), then match the cause:

* **Monthly Usage Quota (single model)** — this per-model quota is set by Modulate. Submit the [support form](/support#contact-us) to request a higher quota.
* **Monthly Credit Limit (all models)** — if your org set an organization-wide Credit Limit, an admin can review or raise it in [Organization settings](https://platform.modulate.ai/dashboard/organization).
* **Concurrency spike** — reduce the number of simultaneous connections and reconnect with a delay. If you need a higher ceiling, request more on the [Concurrency Limits page](https://platform.modulate.ai/dashboard/concurrency-limits) — see [Rate limits](/guides/authentication#rate-limits).

## Audio validation errors

### `400 Bad Request` — wrong format

**Cause:** The audio file format isn't supported by the endpoint you're calling.

| Endpoint                           | Common mistake                                           | Fix                                                                |
| ---------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------ |
| English Fast Transcription (batch) | Sending MP3, WAV, or any format other than Opus          | Convert first: `ffmpeg -i input.mp3 output.opus`                   |
| Deepfake Detection (streaming)     | Sending a container format (MP3, WAV) instead of raw PCM | Convert: `ffmpeg -i input.mp3 -ar 16000 -ac 1 -f s16le output.raw` |

### `422 Unprocessable Entity` — audio too short

**Cause:** The audio is shorter than 0.5 seconds, which is the minimum for Deepfake Detection. Empty files or files with content only in metadata (no actual audio samples) also trigger this.

**Fix:** Verify the actual audio duration not just the file size. Silent files or files where the audio track was stripped can report a non-zero duration but contain no usable samples. Use ffprobe to inspect:

```bash theme={null}
ffprobe -v quiet -show_entries format=duration -of csv=p=0 yourfile.wav
```

### WebSocket close code `1003` — invalid query parameters (Deepfake Detection streaming)

**Cause:** `audio_format`, `sample_rate`, or `num_channels` is missing, misspelled, or unsupported.

**Fix:** All three parameters are required for Deepfake Detection streaming. Check that:

* `audio_format` is a supported raw PCM format (e.g. `s16le`, `f32le`)
* `sample_rate` is an integer (e.g. `16000`)
* `num_channels` is `1` or `2`

### WebSocket close code `4002` -- audio could not be decoded or doesn't match declared format

**Cause:** The audio could not be decoded, or the raw PCM bytes you're sending don't match the `audio_format`, `sample_rate`, or `num_channels` you declared at connection time.

**Fix:** If sending a container format (e.g. WebM, Ogg), make sure the stream is valid and not truncated. If sending raw PCM, confirm that your encoding pipeline produces exactly the format you declared. If you resampled to 16000 Hz but declared `sample_rate=44100`, the model will receive malformed frames.

## Timeout errors

### `504 Gateway Timeout`

**Cause:** Batch processing exceeded 60 seconds. This is uncommon for typical audio files but can happen with very long recordings or during periods of high server load. It can also happen if the file is above the maximum recommended file size of 100 MB.

**Fix:**

* Verify your file is within the recommended length range.
* Verify your file is under 100 MB.
* If the issue is persistent on files that should process quickly, email [support@modulate.ai](mailto:support@modulate.ai) with the file (if possible), the file type, file duration, file size, and endpoint.
* For long recordings, consider splitting into smaller chunks.

### English Fast Transcription — silent 60-second timeout

The English Fast Transcription endpoint has a strict 60-second processing timeout. If you hit it consistently, check:

* The audio is Opus-encoded (the only accepted format)
* The file isn't corrupted or padded with excessive silence

## Server errors

### `502 Bad Gateway` (Multilingual Fast Transcription batch)

**Cause:** Transcription is temporarily unavailable.

**Fix:** Retry with exponential backoff. The response `detail` field is intentionally generic — if the error persists, email [support@modulate.ai](mailto:support@modulate.ai).

### `503 Service Unavailable`

**Cause:** The inference server is temporarily overloaded.

**Fix:** Retry with exponential backoff. Do not hammer the endpoint with immediate retries as this worsens the overload. See the retry pattern under [Rate limit errors](#429-too-many-requests-rest) above.

## Still stuck?

If none of the above matches your situation, email [support@modulate.ai](mailto:support@modulate.ai) with:

* Endpoint URL
* Full request headers (**redact your API key**)
* Response body and status code
* Audio format, duration, and file size