Error Handling

Understanding and handling errors from the Text-to-Speech API.

HTTP Status Codes

Error Response Format

{
    "success": false,
    "error": {
        "code": "INVALID_VOICE",
        "message": "Voice 'InvalidVoice' not found.",
        "category": "validation",
        "resolution": "Use /v1/voices endpoint to get valid voice names",
        "details": {
            "provided": "InvalidVoice",
            "suggestions": ["Peter", "Emma", "James"]
        }
    },
    "request_id": "req_abc123xyz",
    "timestamp": 1699820400.123
}

Common Error Codes

Authentication Errors

Validation Errors

Credit Errors

Rate Limit Errors

Model-Specific Errors

Permission Errors

Retry Strategy

Different errors require different retry approaches:

Error Handling Example

import requests
import time

def generate_speech_with_retry(text, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.post(
                "https://yourvoic.com/api/v1/tts/generate",
                headers={"X-API-Key": "your_api_key"},
                json={
                    "text": text,
                    "voice": "Peter",
                    "language": "en-US"
                }
            )
            
            if response.status_code == 200:
                return response.content
            
            # Parse error response
            error = response.json().get('error', {})
            error_code = error.get('code', '')
            
            # Don't retry these errors
            non_retryable = [
                'INVALID_VOICE', 'INVALID_LANGUAGE', 'INVALID_MODEL',
                'TEXT_TOO_LONG', 'INVALID_API_KEY', 'INSUFFICIENT_CREDITS'
            ]
            
            if error_code in non_retryable:
                raise Exception(f"Non-retryable error: {error_code} - {error.get('message')}")
            
            # Retry with exponential backoff for rate limits
            if response.status_code == 429:
                wait_time = (2 ** attempt) + 1
                print(f"Rate limited. Retrying in {wait_time}s...")
                time.sleep(wait_time)
                continue
            
            # Retry server errors
            if response.status_code >= 500:
                wait_time = 2 ** attempt
                print(f"Server error. Retrying in {wait_time}s...")
                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")

# Usage
try:
    audio = generate_speech_with_retry("Hello, world!")
    with open("output.mp3", "wb") as f:
        f.write(audio)
except Exception as e:
    print(f"Error: {e}")

JavaScript Example

async function generateTTSWithRetry(text, maxRetries = 3) {
    const url = 'https://yourvoic.com/api/v1/tts/generate';
    
    for (let attempt = 0; attempt < maxRetries; attempt++) {
        try {
            const response = await fetch(url, {
                method: 'POST',
                headers: {
                    'Content-Type': 'application/json',
                    'X-API-Key': 'your_api_key'
                },
                body: JSON.stringify({
                    text: text,
                    voice: 'Peter',
                    language: 'en-US'
                })
            });
            
            if (response.ok) {
                return await response.blob();
            }
            
            const error = await response.json();
            const errorCode = error.error?.code;
            
            // Don't retry these errors
            const nonRetryable = [
                'INVALID_VOICE', 'INVALID_LANGUAGE', 'INVALID_MODEL',
                'TEXT_TOO_LONG', 'INVALID_API_KEY', 'INSUFFICIENT_CREDITS'
            ];
            
            if (nonRetryable.includes(errorCode)) {
                throw new Error(`Non-retryable: ${errorCode} - ${error.error?.message}`);
            }
            
            // Retry rate limits with backoff
            if (response.status === 429) {
                const retryAfter = response.headers.get('Retry-After') || (2 ** attempt);
                console.log(`Rate limited. Waiting ${retryAfter}s...`);
                await new Promise(r => setTimeout(r, retryAfter * 1000));
                continue;
            }
            
            // Retry server errors
            if (response.status >= 500) {
                const waitTime = Math.pow(2, attempt) * 1000;
                console.log(`Server error. Retrying in ${waitTime}ms...`);
                await new Promise(r => setTimeout(r, waitTime));
                continue;
            }
            
            throw new Error(`Request failed: ${errorCode}`);
        } catch (e) {
            if (attempt === maxRetries - 1) throw e;
        }
    }
    
    throw new Error('Max retries exceeded');
}

// Usage
generateTTSWithRetry("Hello, world!")
    .then(blob => {
        const url = URL.createObjectURL(blob);
        const audio = new Audio(url);
        audio.play();
    })
    .catch(e => console.error('Error:', e));

Debugging Tips

• Save the request_id - Include it when contacting support for faster resolution
• Check response headers - Rate limit headers show remaining quota
• Validate locally - Check text length and parameters before making API calls
• Use the health endpoint - Check /v1/health to verify API availability
• Log full responses - The resolution field often contains the fix

# Check API health status
curl -s https://yourvoic.com/api/v1/health | jq

# Test your API key
curl -s -H "X-API-Key: your_key" \
  https://yourvoic.com/api/v1/usage | jq

Best Practices

• Validate input - Check text length and parameters before sending
• Handle rate limits - Implement exponential backoff
• Monitor credits - Check balance before large batches
• Log errors - Keep track of error codes for debugging
• Test edge cases - Handle empty text, special characters, long content