Error Handling

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "category": "error_category",
    "resolution": "Suggested steps to fix the issue"
  },
  "request_id": "req_abc123xyz",
  "timestamp": 1699820400.123
}

import requests
import time

def generate_tts_with_retry(text, voice_id, max_retries=3):
    """Generate TTS with automatic retry on transient errors."""
    url = "https://yourvoic.com/api/v1/tts/generate"
    headers = {"X-API-Key": "your_api_key"}
    data = {"text": text, "voice_id": voice_id}
    
    for attempt in range(max_retries):
        response = requests.post(url, json=data, headers=headers)
        
        if response.status_code == 200:
            return response.content  # Success
        
        error = response.json().get("error", {})
        error_code = error.get("code")
        
        # Don't retry client errors (except rate limits)
        if response.status_code == 400:
            raise ValueError(f"Invalid request: {error.get('message')}")
        
        if response.status_code == 401:
            raise AuthError(f"Authentication failed: {error.get('message')}")
        
        if response.status_code == 403:
            raise PermissionError(f"Access denied: {error.get('message')}")
        
        if response.status_code == 429:
            # Rate limited - wait and retry
            retry_after = int(response.headers.get("Retry-After", 60))
            print(f"Rate limited. Waiting {retry_after}s...")
            time.sleep(retry_after)
            continue
        
        if response.status_code >= 500:
            # Server error - exponential backoff
            wait_time = (2 ** attempt) + random.random()
            print(f"Server error. Retrying in {wait_time:.1f}s...")
            time.sleep(wait_time)
            continue
    
    raise Exception(f"Max retries exceeded. Last error: {error_code}")

async function generateTTSWithRetry(text, voiceId, 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, voice_id: voiceId })
            });
            
            if (response.ok) {
                return await response.blob();
            }
            
            const error = await response.json();
            const errorCode = error.error?.code;
            
            // Handle specific errors
            switch (response.status) {
                case 400:
                    throw new Error(`Invalid request: ${error.error?.message}`);
                case 401:
                    throw new Error(`Auth failed: ${error.error?.message}`);
                case 403:
                    throw new Error(`Access denied: ${error.error?.message}`);
                case 429:
                    const retryAfter = response.headers.get('Retry-After') || 60;
                    console.log(`Rate limited. Waiting ${retryAfter}s...`);
                    await sleep(retryAfter * 1000);
                    continue;
                default:
                    if (response.status >= 500) {
                        const waitTime = Math.pow(2, attempt) * 1000;
                        console.log(`Server error. Retrying in ${waitTime}ms...`);
                        await sleep(waitTime);
                        continue;
                    }
            }
        } catch (e) {
            if (attempt === maxRetries - 1) throw e;
        }
    }
    
    throw new Error('Max retries exceeded');
}

const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));

# 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