Error handling

{
  "type": "Error",
  "error_code": 3006,
  "error": "Bad connection parameters: sample_rate: sample_rate 12345 not in supported set [8000, 16000, 22050, 24000, 44100, 48000]",
  "error_type": "invalid_parameter",
  "retryable": false,
  "param": "sample_rate",
  "retry_after_seconds": null
}

​

Close codes

​

Error types

​

In the SDKs

import asyncio
import base64
import json
import os
import random

import websockets

URL = "wss://tts.us.assemblyai.com/v1/ws?voice_id=49c443a4-8a1d-5f7e-b70b-98bdbd9823c3&language=english"
HEADERS = {"Authorization": os.environ["ASSEMBLYAI_API_KEY"]}


class AuthError(Exception):
    """1008. Fix the credential or the account; retrying unchanged fails again."""


class BadRequest(Exception):
    """3006 for a bad parameter or frame, 3012 or 3014 for a cloned voice, or 1009. Fix the request first."""


class Transient(Exception):
    """1011, 1012, 3005, 3009, a lost connection, or a failure to connect. Back off, then reconnect."""

    def __init__(self, text, retry_after=None):
        super().__init__(text)
        self.retry_after = retry_after


class Paced(Exception):
    """3010 or 3011. Reconnect, but send text slower or read audio faster."""


class SessionOver(Exception):
    """3008, or an inactivity 3006. Nothing is wrong; open a new session when you need one."""


def raise_for_error(message):
    code, text = message["error_code"], message["error"]
    error_type = message.get("error_type")
    if code == 1008:
        raise AuthError(text)
    if code in (1011, 1012, 3005, 3009):
        raise Transient(text, message.get("retry_after_seconds"))
    if code in (3010, 3011):
        raise Paced(text)
    if code == 3008 or error_type == "inactivity_timeout":
        raise SessionOver(text)
    if code in (3006, 3012, 3014):
        raise BadRequest(f"{error_type}: {text}")
    raise RuntimeError(f"{code}: {text}")


async def speak(text):
    """One session: connect, speak `text` once, return the raw PCM bytes."""
    pcm = bytearray()
    try:
        async with websockets.connect(URL, additional_headers=HEADERS) as ws:
            first = json.loads(await ws.recv())
            if first["type"] == "Error":
                raise_for_error(first)

            await ws.send(json.dumps({"type": "Generate", "text": text}))
            await ws.send(json.dumps({"type": "Flush"}))

            async for raw in ws:
                message = json.loads(raw)
                kind = message.get("type")
                if kind == "Audio":
                    pcm += base64.b64decode(message["audio"])
                elif kind == "FlushDone":
                    await ws.send(json.dumps({"type": "Terminate"}))
                elif kind == "Termination":
                    return bytes(pcm)
                elif kind == "Error":
                    raise_for_error(message)
                # WordBoundaries, and any type you do not recognize: ignore.
    except websockets.ConnectionClosedError as e:
        # No Error frame: 1006 (connection lost), 1011 (ping unanswered) or 1009 (message over 1 MiB).
        code = e.rcvd.code if e.rcvd else 1006
        if code == 1009:
            raise BadRequest("a message over 1 MiB was rejected; split the text")
        raise Transient(f"connection closed ({code}) before Termination")
    except (OSError, TimeoutError, websockets.InvalidHandshake) as e:
        # The socket never opened: DNS, TCP, TLS, or a non-101 upgrade response.
        raise Transient(f"could not connect: {e}")
    # The loop ended without Termination: the server closed the socket, so the session is over.
    raise SessionOver("socket closed before Termination")


async def main():
    for attempt in range(5):
        try:
            pcm = await speak("Hi, thanks for calling. How can I help you today?")
            print(f"got {len(pcm)} bytes of audio")
            return
        except (AuthError, BadRequest) as e:
            raise SystemExit(f"fix before retrying: {e}")
        except Transient as e:
            backoff = min(30, 0.5 * 2 ** attempt) * (0.5 + random.random())
            delay = max(backoff, e.retry_after or 0)
            print(f"Transient: {e}; retrying in {delay:.1f}s")
            await asyncio.sleep(delay)
        except Paced as e:
            delay = min(30, 0.5 * 2 ** attempt) * (0.5 + random.random())
            print(f"Paced: {e}; retrying in {delay:.1f}s")
            await asyncio.sleep(delay)
        except SessionOver as e:
            print(f"session ended: {e}; opening a new one")
    raise SystemExit("gave up after 5 attempts")


asyncio.run(main())

​

A clean close is still a close

const NO_RETRY = new Set([1008, 3006, 3012, 3014]); // fix the credential or the request first
let attempt = 0; // reset to 0 when Begin arrives

ws.onclose = (event) => {
  setReady(false);
  // event.reason normally carries no cause; that was in the Error frame.
  showError(`session closed (${event.code})`);
  if (NO_RETRY.has(event.code)) return;
  if (!stillNeeded()) return; // your own check: the user is done, so no new socket
  // 1000 after your own Terminate, 3008 at expires_at, 1006 on a network drop and the
  // transient codes all end up here: the socket is gone either way, so open a new one.
  const delay = Math.min(30_000, 500 * 2 ** attempt++) * (0.5 + Math.random());
  setTimeout(async () => connect(await fetchTemporaryToken()), delay);
};

​

Retry guidance

• 1008 is a credential or account problem, and retrying unchanged will not help. Unauthorized: missing Authorization header or token query param means no credential reached the server. Unauthorized: Invalid API key means the key or token was rejected; the raw key and Bearer <key> both work, so check the key itself. Unauthorized: Signature has expired means the temporary token expired: mint a new token and reconnect. A message that names your account or balance, such as Unauthorized: Insufficient funds, has to be fixed on the account first.
• 3006 for a bad parameter, a malformed frame or an oversized Generate means the request is wrong; error_type and param say what to fix. Fix it before reconnecting; retrying unchanged fails identically. A parameter given more than once reads Bad connection parameters: <parameter>: must be given at most once (given 2 times): send it once. For an AssemblyAI voice this connection does not serve, the error text lists the voices that are available on it, by their voice_id slugs. A 3006 after Begin whose text begins Text contains a and ends Send shorter sentences. means a piece of your text, split as How text is read describes, did not fit the model with this voice. The server splits every text into pieces that fit, so this is rare and points to a fault on our side: report it with the session’s id. Sending the text again in shorter sentences avoids it.
• 3012 and 3014 concern a cloned voice, and retrying unchanged fails the same way, except for a pairing still in progress. 3012 is a voice that cannot be used: voice_not_found (check the ID, that an AssemblyAI voice is named by its library slug such as aai-jane, and that you connect to the host of the voice’s data zone), voice_expired (create the voice again from a new consented recording; to keep a voice, renew its consent before it expires) or voice_blocked (contact support). 3014 voice_not_paired means the voice has no ready pairing with the session’s model: if the voice was just paired with the model, try again once the pairing is ready; otherwise name a model the voice is paired with in model_id, or check the voice in the AssemblyAI dashboard. The error text says what to do; The texts of 3014 lists them. A 3006 with error_type not_owner means extend_biometric_consent was set on a voice that another account owns: open the session without it.
• 3006 from the idle timeout is not a request error. Every session closes after two minutes without a frame in either direction, or after the shorter inactivity_timeout you set. Its error_type is inactivity_timeout, and the error text begins No message received for and ends Send KeepAlive frames to hold an idle session open. Reconnect when you have something to say, or send KeepAlive at least every two minutes while idle if you want the socket to stay open.
• 1011, 1012, 3005 and 3009 are transient. Back off exponentially with jitter, then reconnect, and wait at least retry_after_seconds when the Error frame sets it. 1011 is an internal error while authenticating. 1012 (The server is restarting; reconnect to continue the session.) means the server is being replaced; the next session lands on another one. 3005 is a failure on the server side, for example The TTS service is temporarily unavailable; please reconnect and retry, or Voice service temporarily unavailable; please retry. when the service that routes voices cannot answer at connect; re-send the request that was in flight. A 3005 with error_type at_capacity means the service had no room for the session: This server is at capacity; please retry in 2 seconds. before your credentials are read, or The TTS service is at capacity; please retry in 3 seconds. after Begin. Wait retry_after_seconds before reconnecting, and back off further if it repeats. 3009 (Too many sessions opened for this account in the last minute (allowance 100 per minute); retry in 17 s.) means your account started more sessions in the current one-minute window than its limit allows, and retry_after_seconds, between 1 and 60, is the time until the next window starts: a session opened after that wait is counted in the new window. As for Streaming Speech-to-Text, the limit counts new sessions per minute, not sessions currently open, so closing sessions early does not help; opening fewer does. A voice agent call opens one session, so the limit is the number of calls that can start in a minute. The number in the text is your starting limit; on a paid plan the limit in force can be higher. Keep one socket open and send many requests through it rather than opening a new socket for every utterance. Your limit is your Streaming Speech-to-Text limit, shown on the dashboard, counted separately from your speech-to-text sessions. See Rate limits for how limits scale with usage.
• 3010 and 3011 mean pacing, not a broken request. 3010 has three triggers: more than 8000 characters sent but not yet synthesized (Input text rate exceeded: ...), more than 20 Flush, KeepAlive, Cancel or empty Generate frames per second sustained (Control frame rate exceeded: ...), or more than 10,000 messages waiting to be handled. Send text at roughly the pace it is spoken and control frames only as the conversation needs them. 3011 means 300 seconds of synthesized audio were waiting for a client that had stopped reading; read from the socket at least as fast as the audio plays. Such a client usually cannot receive the Error frame either and sees 1006 when the socket is torn down. In both cases reconnect, but do not resend the same burst. See Limits.
• 3008 (Session reached its maximum duration; open a new connection to continue) is routine on a long-lived socket, not a fault. Sessions last one hour by default; Begin.expires_at gives the exact time, and a temporary token with a shorter max_session_duration_seconds brings it forward. At expires_at the server stops taking new input, speaks what you have already sent, then closes. Read expires_at and open a replacement socket a little before it so the next request has somewhere to go.
• 1006 is the connection being lost without a close handshake, on your side or because the server was replaced. Reconnect.
• 1009 means a message over 1 MiB, counted after its fragments are joined. A well-formed client cannot reach it, because Generate is capped at 2000 characters; check what else you are putting in the message.

​

HTTP API errors

​

The texts of 3014

​

The same condition in each API

​

Related

• Message frames: the Error frame and where it sits in the frame order.
• Limits: the thresholds behind 3006, 3008, 3009, 3010 and 3011.
• WebSocket API basics: inactivity_timeout, and the parameters a 3006 can name.
• Voice cloning: the errors of a session with a cloned voice, and what to do about each.
• Authenticate with a temporary token: minting the token a browser client reconnects with.
• HTTP API basics: the error bodies and codes of the HTTP API.

​

Need help?