Error Handling
Understanding and handling errors from the Speech-to-Text API.
HTTP Status Codes
| Code | Description | Common Cause |
|---|
| 200 | Success | Request completed successfully |
| 400 | Bad Request | Invalid parameters or file format |
| 401 | Unauthorized | Invalid or missing API key |
| 402 | Payment Required | Insufficient credits |
| 413 | Payload Too Large | File exceeds 25MB limit |
| 429 | Too Many Requests | Rate limit exceeded |
| 500 | Internal Server Error | Server-side issue |
| 503 | Service Unavailable | Temporary overload |
Error Response Format
{
"success": false,
"error": {
"code": "INVALID_FILE_FORMAT",
"message": "Unsupported audio format. Please use MP3, WAV, M4A, or WebM.",
"details": {
"received_format": "text/plain",
"supported_formats": ["audio/mpeg", "audio/wav", "audio/mp4", "audio/webm"]
}
}
}
Common Error Codes
File Errors
| Error Code | Description | Solution |
|---|
NO_FILE_PROVIDED | No audio file in request | Include file in multipart form data |
INVALID_FILE_FORMAT | Unsupported audio format | Convert to MP3, WAV, M4A, or WebM |
FILE_TOO_LARGE | File exceeds 25MB | Compress or split the audio file |
CORRUPTED_FILE | Cannot read audio file | Re-encode or use different file |
EMPTY_AUDIO | No audio data in file | Check file contains audio |
Authentication Errors
| Error Code | Description | Solution |
|---|
MISSING_API_KEY | No API key provided | Add X-API-Key header |
INVALID_API_KEY | API key not recognized | Verify your API key |
API_KEY_DISABLED | API key has been disabled | Contact support |
Credit Errors
| Error Code | Description | Solution |
|---|
INSUFFICIENT_CREDITS | Not enough credits for transcription | Add credits to account |
CREDIT_CHECK_FAILED | Unable to verify credits | Retry request |
Rate Limit Errors
| Error Code | Description | Solution |
|---|
RATE_LIMIT_EXCEEDED | Too many requests | Wait and retry with backoff |
CONCURRENT_LIMIT | Too many concurrent requests | Wait for other requests to complete |
WebSocket Errors
| Error Code | Description | Solution |
|---|
SESSION_LIMIT_REACHED | Max session duration exceeded | Start new session |
IDLE_TIMEOUT | No speech for 60 seconds | Reconnect when ready to speak |
INVALID_AUDIO_FORMAT | Audio not in expected format | Use Linear16, FLAC, or Opus |
Error Handling Best Practices
import requests
import time
def transcribe_with_retry(file_path, max_retries=3):
for attempt in range(max_retries):
try:
response = requests.post(
"https://yourvoic.com/api/v1/stt/transcribe",
headers={"X-API-Key": "your_api_key"},
files={"file": open(file_path, "rb")},
data={"model": "cipher-fast"}
)
if response.status_code == 200:
return response.json()
error = response.json().get('error', {})
error_code = error.get('code', '')
# Don't retry these errors
if error_code in ['INVALID_FILE_FORMAT', 'INVALID_API_KEY', 'INSUFFICIENT_CREDITS']:
raise Exception(f"Non-retryable error: {error_code}")
# Retry with exponential backoff
if response.status_code in [429, 503]:
wait_time = (2 ** attempt) + 1
print(f"Retrying in {wait_time} seconds...")
time.sleep(wait_time)
continue
raise Exception(f"Request failed: {error}")
except requests.RequestException as e:
if attempt < max_retries - 1:
time.sleep(2 ** attempt)
continue
raise
raise Exception("Max retries exceeded")