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.

Agent runs

Several run codes share a status, so branch on code here too.

Stores

Hosted APIs

Answered on your own subdomain to your API’s callers, so they read like any other envelope. The daily caps release a slot the moment a request they admitted 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.

Idempotency on retries

Retrying a mutating POST (anything that creates a call, batch, purchase, or resource) risks performing the action twice if the first attempt succeeded but the response was lost.

Only endpoints that explicitly document Idempotency-Key support will replay the original response. Check the endpoint reference before relying on idempotency protection.

For supported endpoints, send an Idempotency-Key header with a unique value per logical operation. Reuse the same key on every retry:

curl -X POST https://api.speechify.ai/v1/agents/outbound-calls \
  -H "Authorization: Bearer $SPEECHIFY_API_KEY" \
  -H "Idempotency-Key: 4c7f0a78-0a61-42b4-8b8a-60b307b18f0c" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "agent_demo0001", "to": "+15555550123"}'

The server runs the request once and replays the original response on retries. Endpoints that do not document idempotency support will ignore the header. See Idempotency for details.

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