Troubleshooting

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:

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. This per-model quota is set by Modulate — submit the support form 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
Model not enabled for your org	`"model access not enabled"`	Check the limits specified for your API key; otherwise contact 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:

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; otherwise contact 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:

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 — see 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, then match the cause:

Monthly Usage Quota (single model) — this per-model quota is set by Modulate. Submit the support form 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.
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 — see 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:

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

`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 above.

Still stuck?

If none of the above matches your situation, email support@modulate.ai with:

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

Contact

Resources

Authentication errors

`401 Unauthorized`

`403 Forbidden` (REST)

WebSocket close code `4001` (Multilingual Transcription streaming)

WebSocket close code `4003`

Rate limit errors

`429 Too Many Requests` (REST)

WebSocket close code `4029`

Audio validation errors

`400 Bad Request` — wrong format

`422 Unprocessable Entity` — audio too short

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

WebSocket close code `4002` — audio could not be decoded or doesn’t match declared format

Timeout errors

`504 Gateway Timeout`

English Fast Transcription — silent 60-second timeout

Server errors

`502 Bad Gateway` (Multilingual Fast Transcription batch)

`503 Service Unavailable`

Still stuck?

​Authentication errors

​401 Unauthorized

​403 Forbidden (REST)

​WebSocket close code 4001 (Multilingual Transcription streaming)

​WebSocket close code 4003

​Rate limit errors

​429 Too Many Requests (REST)

​WebSocket close code 4029

​Audio validation errors

​400 Bad Request — wrong format

​422 Unprocessable Entity — audio too short

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

​WebSocket close code 4002 — audio could not be decoded or doesn’t match declared format

​Timeout errors

​504 Gateway Timeout

​English Fast Transcription — silent 60-second timeout

​Server errors

​502 Bad Gateway (Multilingual Fast Transcription batch)

​503 Service Unavailable

​Still stuck?

Authentication errors

`401 Unauthorized`

`403 Forbidden` (REST)

WebSocket close code `4001` (Multilingual Transcription streaming)

WebSocket close code `4003`

Rate limit errors

`429 Too Many Requests` (REST)

WebSocket close code `4029`

Audio validation errors

`400 Bad Request` — wrong format

`422 Unprocessable Entity` — audio too short

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

WebSocket close code `4002` — audio could not be decoded or doesn’t match declared format

Timeout errors

`504 Gateway Timeout`

English Fast Transcription — silent 60-second timeout

Server errors

`502 Bad Gateway` (Multilingual Fast Transcription batch)

`503 Service Unavailable`

Still stuck?