Error Codes

The SpeakEasy API uses standard HTTP status codes to indicate the outcome of each request. Successful requests return a 2xx status code, client errors return 4xx, and server errors return 5xx.

When a request fails, the API returns a JSON response body with an error object containing a machine-readable type and a human-readable message:

{
  "error": {
    "type": "...",
    "message": "..."
  }
}

Error Codes Reference

The following table lists every error code the API may return, along with a description and recommended solution.

Status Code	Type	Description	Solution
400	`invalid_request`	The request is missing one or more required parameters.	Check the request body and ensure all required fields are included.
400	`invalid_file_format`	The uploaded audio file is in an unsupported format.	Use a supported format such as MP3, WAV, FLAC, OGG, or WebM.
400	`file_too_large`	The uploaded file exceeds the 100 MB size limit.	Pass a URL to the file instead, or compress/split the audio before uploading.
400	`text_too_long`	The TTS input text exceeds the 4 096-character limit.	Split the text into smaller chunks and make multiple requests.
401	`invalid_api_key`	The API key is missing or invalid.	Verify the `Authorization` header contains a valid Bearer token.
401	`expired_api_key`	The API key has been revoked or has expired.	Generate a new API key from your dashboard.
404	`not_found`	The requested endpoint does not exist.	Check the URL and ensure you are using a valid API path.
413	`payload_too_large`	The overall request body exceeds the maximum allowed size.	Reduce the size of the request payload.
422	`invalid_parameter`	A parameter value is out of range or otherwise invalid.	Review the parameter documentation for accepted values.
429	`rate_limit_exceeded`	You have sent too many requests in a given time window.	Implement exponential backoff and respect the `Retry-After` header.
500	`internal_error`	An unexpected error occurred on the server.	Wait a moment and retry the request. If the issue persists, contact support.
503	`service_unavailable`	The service is temporarily unavailable due to maintenance or high load.	Retry with exponential backoff. Check the status page for incidents.

Example Error Response

Here is a complete example of an error response returned when an invalid API key is provided:

curl -s https://api.tryspeakeasy.io/v1/audio/transcriptions \
  -H "Authorization: Bearer invalid-key" \
  -F file=@audio.mp3 \
  -F model=whisper-1

Response (401 Unauthorized):

{
  "error": {
    "type": "invalid_api_key",
    "message": "The API key provided is invalid or has been deactivated. Please check your key and try again."
  }
}

Handling Errors

We recommend building retry logic into your integration for transient errors (429 and 5xx status codes). Use exponential backoff to space out retries and avoid overwhelming the API when it is under load.

Retry Strategy

Make the initial request.
If the response status is 429, 500, or 503, wait and retry.
For each subsequent retry, double the wait time (e.g., 1 s, 2 s, 4 s, 8 s).
Add a small random jitter to prevent thundering-herd effects.
Give up after a maximum number of retries (e.g., 5).

Python Example

import time
import random
import requests

def call_api_with_retry(url, headers, data, max_retries=5):
    """Make an API request with exponential backoff for transient errors."""
    for attempt in range(max_retries):
        response = requests.post(url, headers=headers, data=data)

        if response.status_code == 200:
            return response.json()

        # Retry on rate-limit or server errors
        if response.status_code in (429, 500, 503):
            wait = (2 ** attempt) + random.uniform(0, 1)
            print(f"Request failed ({response.status_code}). Retrying in {wait:.1f}s...")
            time.sleep(wait)
            continue

        # Non-retryable client error — raise immediately
        error = response.json().get("error", {})
        raise Exception(
            f"API error {response.status_code}: "
            f"[{error.get('type')}] {error.get('message')}"
        )

    raise Exception("Max retries exceeded")

JavaScript Example

async function callApiWithRetry(url, options, maxRetries = 5) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);

    if (response.ok) {
      return response.json();
    }

    // Retry on rate-limit or server errors
    if ([429, 500, 503].includes(response.status)) {
      const wait = 2 ** attempt + Math.random();
      console.log(`Request failed (${response.status}). Retrying in ${wait.toFixed(1)}s...`);
      await new Promise((resolve) => setTimeout(resolve, wait * 1000));
      continue;
    }

    // Non-retryable client error — throw immediately
    const { error } = await response.json();
    throw new Error(`API error ${response.status}: [${error.type}] ${error.message}`);
  }

  throw new Error("Max retries exceeded");
}

For 429 responses, also check the Retry-Afterheader if present — it indicates exactly how many seconds to wait before your next request will be accepted.