Error Handling

All API errors return a JSON object with an error field.

Error Format

{
  "error": "human-readable error message"
}

HTTP Status Codes

Code	Meaning
400	Bad request — check your request body
401	Unauthorized — invalid or missing authentication
404	Not found — resource doesn't exist
409	Conflict — resource state conflict
429	Too many requests — rate limit exceeded
500	Internal server error — retry later

Common Errors

Authentication

Error	Code	Fix
missing Authorization header	401	Add Authorization: Bearer <key> header
invalid api key	401	Check the key is correct and not revoked
api key has been revoked	401	Create a new key
token expired	401	Refresh your JWT token

Transcription

Error	Code	Fix
no transcription credits left	402	Purchase a minute package
file duration exceeds allowed limit for your plan	400	Use a shorter file
only one transcription can be in progress at a time	409	Wait for current job to finish
daily usage limit exceeded	429	Wait until the next day or upgrade
transcription not found	404	Check the transcription ID

TTS

Error	Code	Fix
input text exceeds maximum length	400	Keep text under 5,000 characters
invalid voice	400	Use a supported voice name
tts job not found	404	Check the job ID

Retry Strategy

For 429 and 5xx errors, implement exponential backoff:

import time
import requests

def api_call_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        if response.status_code == 429 or response.status_code >= 500:
            wait = 2 ** attempt
            time.sleep(wait)
            continue
        return response
    raise Exception("Max retries exceeded")