Troubleshooting

Common errors, causes, and solutions when using the ShunyaLabs transcription APIs.

File Size Error (413)

HTTP 413: Request Entity Too Large
File 'meeting.wav' is 12.45 MB. Maximum allowed size is 10 MB.

Split audio into smaller segments
Reduce bitrate or sample rate
Compress using FFmpeg:

ffmpeg -i input.wav -ar 16000 -ac 1 -b:a 64k output.wav

Authentication Error (401)

HTTP 401: Unauthorized

Verify API key is correct
Ensure API key is sent in headers
Remove extra spaces or line breaks

Bad Request (400)

HTTP 400: Bad Request

Cause	Solution
Unsupported file format	Use WAV, MP3, M4A or supported formats
Invalid parameter value	Verify language_code, chunk_size
Corrupted audio file	Test with a different file
Missing required fields	Ensure file parameter is included

Method Not Allowed (405)

HTTP 405: Method Not Allowed

Use POST instead of GET
Correct: requests.post(...)
Incorrect: requests.get(...)

Audio Processing Failed (500)

HTTP 500: Audio splitting by VAD failed

Ensure audio contains speech
Avoid silence-only recordings
Reduce background noise
Verify audio file integrity

Connection Timeout

Check internet connection
Verify API endpoint accessibility
Increase request timeout for large files

response = requests.post(
    url,
    headers=headers,
    files=files,
    data=data,
    timeout=300
)

SSL Certificate Errors

# Not recommended for production
response = requests.post(
    url,
    headers=headers,
    files=files,
    data=data,
    verify=False
)

HTTP Status Codes

Code	Meaning	Action
200	Success	Transcription completed
400	Bad Request	Check parameters
401	Unauthorized	Verify API key
405	Method Not Allowed	Use POST
413	File Too Large	Reduce file size
500	Server Error	Retry or contact support

Debugging Tips

import logging
logging.basicConfig(level=logging.DEBUG)

try:
    result = transcribe_file("audio.wav", api_key)
except Exception as e:
    logging.error(f"Transcription failed: {e}")

def check_audio_file(path):
    import os
    size_mb = os.path.getsize(path) / (1024 * 1024)
    print(f"File size: {size_mb:.2f} MB")
    return size_mb <= 10