Skip to main content

​
Error Handling

The Spitch API returns standard HTTP status codes and structured error responses to help you debug and handle issues gracefully.

​
Common Status Codes

  • 200 - Success
  • 400 - Bad request (invalid parameters)
  • 401 - Unauthorized (invalid or missing API key)
  • 402 - Payment required (insufficient credits)
  • 404 - Not found
  • 422 - Validation error (malformed request)
  • 429 - Rate limit exceeded
  • 500 - Internal server error

​
Error Response Format

{
  "error": {
    "message": "Description of the error",
    "type": "validation_error",
    "code": "invalid_language"
  }
}

​
Best Practices

Python
from spitch import AsyncSpitch
from spitch.exceptions import SpitchError

client = AsyncSpitch()

try:
    response = await client.speech.generate(
        text="Hello world",
        language="en",
        voice="lina"
    )
except SpitchError as e:
    print(f"Spitch API error: {e}")
    # Handle specific error types
    if e.status_code == 401:
        print("Check your API key")
    elif e.status_code == 429:
        print("Rate limit exceeded, try again later")
except Exception as e:
    print(f"Unexpected error: {e}")

​
Common Issues

​
Authentication Problems

Issue: 401 Unauthorized errors Solutions:
  • Verify your API key is correct
  • Check that the API key is properly set in environment variables
  • Ensure you’re using the latest version of the SDK
  • Make sure your API key hasn’t expired
Python
# Test your API key
from spitch import AsyncSpitch

async def test_auth():
    client = AsyncSpitch()  # Uses SPITCH_API_KEY env var
    try:
        usage = await client.files.usage()
        print("✅ Authentication successful")
    except Exception as e:
        print(f"❌ Authentication failed: {e}")

​
Rate Limiting

Issue: 429 Rate Limit Exceeded errors Solutions:
  • Implement exponential backoff
  • Add delays between requests
  • Monitor your usage in the dashboard
  • Consider upgrading your plan for higher limits
Python
import asyncio
from spitch import AsyncSpitch

async def make_request_with_retry(client, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = await client.speech.generate(
                text="Hello world",
                language="en",
                voice="lina"
            )
            return response
        except Exception as e:
            if hasattr(e, 'status_code') and e.status_code == 429:
                wait_time = 2 ** attempt  # Exponential backoff
                print(f"Rate limited, waiting {wait_time}s...")
                await asyncio.sleep(wait_time)
                continue
            raise e
    
    raise Exception("Max retries exceeded")

​
File Upload Issues

Issue: Problems uploading files for translation Solutions:
  • Check file size limits (25MB max)
  • Verify file format is supported
  • Ensure proper file permissions
  • Check your storage quota

​
Audio Format Issues

Issue: Audio transcription or generation failures Solutions:
  • Use supported formats: mp3, wav, m4a, ogg
  • Check audio quality and sample rates
  • Ensure audio files aren’t corrupted
  • Try converting to a different supported format

​
Language and Voice Compatibility

Issue: Voice not working with selected language Solutions:
  • Check the voices documentation for language compatibility
  • Verify the language code is correct (en, yo, ha, ig, am)
  • Make sure you’re using a voice that supports your chosen language

​
Getting Help

If you’re still experiencing issues:
  1. Check the API Reference for detailed parameter information
  2. Join our Discord community for support
  3. Contact our support team at dev@spitch.app
  4. Check the status page for service updates
When reporting issues, please include:
  • Your SDK version
  • The full error message
  • A minimal code example that reproduces the issue
  • Your API request/response (with API keys redacted)
⌘I