Error Handling and Retries

Overview

The Speechify API returns standard HTTP status codes. Transient errors (rate limits, server errors) can be retried safely. Client errors (bad input, auth failures) require fixing the request.

Error types

Transient errors (retry safe)

These errors are temporary. Retry with exponential backoff.

Persistent errors (fix the request)

These errors indicate a problem with the request itself. Retrying without changes will fail again.

Voice-cloning consent verification has its own error family (consent_*) spanning 404, 409, 422 and 502, and three codes share 422, so branch on the code rather than the status. Each code and its fix is listed in When verification fails.

Server errors (retry cautiously)

A 500 error often signals a request that will keep failing (e.g., a bug triggered by specific input). Retry a few times, but stop if it persists. Log the Speechify-Request-Id and contact support.

Retry strategy

Use exponential backoff with jitter for transient errors:

import time
import random
from speechify import Speechify
client = Speechify()
def generate_with_retry(text, max_retries=5):
    for attempt in range(max_retries):
        try:
            return client.audio.speech(
                input=text,
                voice_id="geffen_32",
                model="simba-3.2",
                audio_format="mp3",
            )
        except Exception as e:
            status = getattr(e, 'status_code', None)
            
            # Transient errors: retry with backoff
            if status in [429, 502, 503, 504] and attempt < max_retries - 1:
                # Check for Retry-After header
                retry_after = getattr(e, 'headers', {}).get('Retry-After')
                if retry_after:
                    time.sleep(int(retry_after))
                else:
                    # Exponential backoff with jitter
                    delay = (2 ** attempt) + random.uniform(0, 1)
                    time.sleep(delay)
            # 500: retry cautiously
            elif status == 500 and attempt < 3:
                delay = (2 ** attempt) + random.uniform(0, 1)
                time.sleep(delay)
            else:
                raise

Retry-After header

When present, Retry-After tells you how long to wait (in seconds) before retrying. Respect this value to avoid hammering the API.

HTTP/1.1 429 Too Many Requests
Retry-After: 5

Wait at least 5 seconds before the next attempt.

Logging and debugging

Always log the Speechify-Request-Id from error responses. Include it when contacting support:

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Retry after 10 seconds."
  },
  "request_id": "req_7f3a2c1b4d5e6f7a"
}

The request_id uniquely identifies the failed request in Speechify’s logs.

FAQ