Errors & Retries

Prerequisites

Create a Fish Audio account

Sign up on fish.audio
Fill in your details to create an account, complete steps to verify your account.
Log in to your account and open Get Started

Get your API key

Once you have an account, you’ll need an API key to authenticate your requests.

Log in and open Get Started
Click “Get your API key”: the key is created in one click and shown only once
Copy your key and store it securely

Keep your API key secret! Never commit it to version control or share it publicly.

Exception hierarchy

Every SDK error inherits from FishAudioError. HTTP failures raise APIError or one of its subclasses, which expose .status, .message, and .body.

Exception	Raised when	Notes
`AuthenticationError`	`401`	Missing or invalid API key
`PermissionError`	`403`	Key lacks permission for the resource
`NotFoundError`	`404`	Voice model id not found
`RateLimitError`	`429`	Rate limit / quota exceeded
`ServerError`	`5xx`	Transient server-side failure
`APIError`	any other non-2xx	Base for the above; `status == 422` for invalid parameters
`WebSocketError`	realtime stream failed mid-session	Reconnect rather than retrying the same socket
`DependencyError`	a required system tool is missing (e.g. ffmpeg for `play()`)	Carries `.dependency` and `.install_command`

Invalid request parameters come back as an APIError with status == 422. Catch APIError, not a separate ValidationError (none is raised at runtime).

Handling errors

Install the Python SDK first: pip install fish-audio-sdk.

from fishaudio import FishAudio
from fishaudio.exceptions import (
    AuthenticationError,
    RateLimitError,
    NotFoundError,
    APIError,
    FishAudioError,
)

client = FishAudio()

try:
    audio = client.tts.convert(text="Hello!", reference_id="maybe-missing", model="s2.1-pro-free")
except AuthenticationError:
    print("Invalid API key")
except RateLimitError:
    print("Rate limited: back off and retry")
except NotFoundError:
    print("That voice model does not exist")
except APIError as e:
    print(f"API error {e.status}: {e.message}")  # includes 422 validation
except FishAudioError as e:
    print(f"SDK error: {e}")  # e.g. WebSocketError, DependencyError

import asyncio
from fishaudio import AsyncFishAudio
from fishaudio.exceptions import RateLimitError, APIError, FishAudioError

async def main():
    async with AsyncFishAudio() as client:
        try:
            audio = await client.tts.convert(text="Hello!", model="s2.1-pro-free")
        except RateLimitError:
            print("Rate limited: back off and retry")
        except APIError as e:
            print(f"API error {e.status}: {e.message}")
        except FishAudioError as e:
            print(f"SDK error: {e}")

asyncio.run(main())

Retries

The Python client does not retry automatically. Add your own backoff where it matters, typically around RateLimitError and ServerError:

import time
from fishaudio import FishAudio
from fishaudio.exceptions import RateLimitError, ServerError

client = FishAudio()

def convert_with_retry(text: str, max_retries: int = 3) -> bytes:
    for attempt in range(max_retries):
        try:
            return client.tts.convert(text=text, model="s2.1-pro-free")
        except (RateLimitError, ServerError):
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)  # exponential backoff
    raise RuntimeError("unreachable")

RequestOptions accepts a max_retries field, but the current client does not act on it. Use an explicit loop like the one above.

Timeouts

The request timeout is set on the client (seconds; default 240):

from fishaudio import FishAudio

client = FishAudio(timeout=30.0)

Override headers or timeout for a single request with request_options:

from fishaudio.core.request_options import RequestOptions

audio = client.tts.convert(
    text="Hello!",
    model="s2.1-pro-free",
    request_options=RequestOptions(timeout=15.0, additional_headers={"X-Trace": "abc"}),
)

If you inject your own httpx_client, the client-level timeout, base_url, and Authorization header are not applied to it. Configure those on the client you pass in.

Exceptions API reference
Real-time WebSocket: WebSocketError handling

Set Up the SDK

Cookbook

Best Practices

Integrations

Compatible APIs

Self-Hosting

More

Prerequisites

Exception hierarchy

Handling errors

Retries

Timeouts

​Prerequisites

​Exception hierarchy

​Handling errors

​Retries

​Timeouts

​Related

Prerequisites

Exception hierarchy

Handling errors

Retries

Timeouts

Related