Skip to main content

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.

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)

Two different problems return 403:
ScenarioResponse detailFix
Monthly quota exceeded"monthly limit reached" or similarCheck your Usage Dashboard; update your Monthly Credit Limit 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 (STT Streaming)

Cause: The api_key query parameter is missing or contains an invalid key. Fix: Pass the key at connection time: 
wss://modulate-developer-apis.com/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 email support@modulate.ai to request a higher limit.

​
WebSocket close code 4029

Cause: Rate limit exceeded at WebSocket handshake — either the monthly quota is full or the concurrency limit is hit. Fix: Check your Usage Dashboard. If the monthly limit is hit, update your Monthly Credit Limit in Organization settings. If it’s a concurrency spike, reduce the number of simultaneous connections and reconnect with a delay.

​
Audio validation errors

​
400 Bad Request — wrong format

Cause: The audio file format isn’t supported by the endpoint you’re calling.
EndpointCommon mistakeFix
STT Batch English VFastSending MP3, WAV, or any format other than OpusConvert first: ffmpeg -i input.mp3 output.opus
SVD StreamingSending a container format (MP3, WAV) instead of raw PCMConvert: 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 (SVD Streaming)

Cause: audio_format, sample_rate, or num_channels is missing, misspelled, or unsupported. Fix: All three parameters are required for SVD 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 data doesn’t match declared format

Cause: The raw PCM bytes you’re sending don’t match the audio_format, sample_rate, or num_channels you declared at connection time. Fix: 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.

​
STT Batch English VFast — silent 60-second timeout

The VFast 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

​
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