Error Handling Guide

{
  "success": false,
  "error": "Error message describing what went wrong",
  "code": "ERROR_CODE",
  "details": {
    // Additional error details (optional)
  }
}

{
  "success": false,
  "error": "Missing required parameter: audio_file",
  "code": "MISSING_PARAMETER"
}

{
  "success": false,
  "error": "No API token provided",
  "message": "Please provide an API key in Authorization header"
}

{
  "success": false,
  "error": "Service not allowed for this token",
  "message": "Token validation failed"
}

{
  "success": false,
  "error": "Rate limit exceeded",
  "rate_limit": {
    "current": 61,
    "limit": 60,
    "remaining": 0,
    "reset_at": "2025-11-27T10:30:00Z"
  }
}

{
  "success": false,
  "error": "Internal server error",
  "message": "Model inference failed",
  "details": {
    "error_type": "CUDA_OUT_OF_MEMORY",
    "suggestion": "Try with a smaller file or retry later"
  }
}

import requests

response = requests.post(url, headers=headers, files=files)

if response.status_code == 200:
    result = response.json()
    print("Success:", result)
elif response.status_code == 401:
    print("Authentication failed - check your API token")
elif response.status_code == 429:
    print("Rate limit exceeded - wait and retry")
else:
    print(f"Error {response.status_code}: {response.text}")

import time
from requests.exceptions import RequestException

def api_call_with_retry(url, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.post(url, headers=headers, files=files)
            
            if response.status_code == 429:
                # Rate limited - exponential backoff
                wait_time = 2 ** attempt
                print(f"Rate limited. Waiting {wait_time}s...")
                time.sleep(wait_time)
                continue
            
            if response.status_code >= 500:
                # Server error - retry
                if attempt < max_retries - 1:
                    time.sleep(2 ** attempt)
                    continue
            
            return response
            
        except RequestException as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)
    
    return None

import time

response = requests.post(url, headers=headers, files=files)

if response.status_code == 429:
    # Check for Retry-After header
    retry_after = int(response.headers.get('Retry-After', 60))
    print(f"Rate limited. Waiting {retry_after} seconds...")
    time.sleep(retry_after)
    
    # Retry the request
    response = requests.post(url, headers=headers, files=files)

import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

try:
    response = requests.post(url, headers=headers, files=files)
    response.raise_for_status()
    
except requests.exceptions.HTTPError as e:
    logger.error(f"HTTP Error: {e}")
    logger.error(f"Response: {e.response.text}")
    
except requests.exceptions.RequestException as e:
    logger.error(f"Request failed: {e}")

try:
    response = requests.post(url, headers=headers, files=files, timeout=30)
    response.raise_for_status()
    result = response.json()
    
except requests.exceptions.Timeout:
    print("Request timeout - server is slow or unresponsive")
    
except requests.exceptions.ConnectionError:
    print("Connection error - check network or server status")
    
except requests.exceptions.HTTPError as e:
    print(f"HTTP error: {e.response.status_code}")
    error_data = e.response.json()
    print(f"Error message: {error_data.get('error')}")
    
except requests.exceptions.RequestException as e:
    print(f"Request failed: {e}")

{
  "success": false,
  "error": "Audio file too large",
  "details": {
    "max_size": "100MB",
    "received_size": "150MB"
  }
}

{
  "success": false,
  "error": "Unsupported audio format",
  "details": {
    "supported_formats": ["wav", "mp3", "m4a", "flac"],
    "received_format": "webm"
  }
}

{
  "success": false,
  "error": "No faces detected in image",
  "details": {
    "suggestion": "Ensure image contains clear, front-facing faces"
  }
}

{
  "success": false,
  "error": "Image quality too low",
  "details": {
    "min_resolution": "640x480",
    "received_resolution": "320x240"
  }
}

{
  "success": false,
  "error": "No text detected in image",
  "details": {
    "suggestion": "Ensure image is clear and contains readable text"
  }
}