Errors

Classify any failure in one lookup, and know before you write the handler which ones are worth retrying. Every table on this page is read off the code that raises the error.

Two envelopes

The speech surfaces answer in the OpenAI error shape, because an OpenAI SDK parses that without a translation layer:

{
  "error": {
    "message": "You have insufficient credits for this model. Add credits on the billing page.",
    "type": "insufficient_quota",
    "param": null,
    "code": "insufficient_quota"
  }
}

That covers /v1/audio, /v1/chat, /v1/models, /v1/realtime and /v1/voices — including their authentication failures, and including request validation, which comes back as a 400 rather than FastAPI’s 422. Everything else — interact, story, sessions, memory, keys, organizations — answers FastAPI’s shape:

{ "detail": "No API key 7 in this organization. GET /v1/user/api-keys?include_archived=true lists the ids you can act on." }

Branch on code where there is one; fall back to the status. Both SDKs read both envelopes and put the server’s own sentence on ApiError.message — see SDKs.

HTTP status and code

Status	`code`	What happened	Retry
`400`	`unknown_voice`	`voice` is not a `GET /v1/voices` id, an OpenAI voice name, or the model’s default	No — fix the id
`400`	`model_wrong_kind`	A real model sent to an endpoint that serves a different kind; the message names the right endpoint	No
`400`	pydantic’s own reason (`missing`, `string_too_long`, `less_than_equal`)	A request field failed validation; `param` names it	No
`400`	—	`response_format` is not one this model advertises; the message lists the ones that are	No
`400`	`tts_input_too_long`	Over `SPEECH_MAX_CHARS_PER_GENERATION`; the 4,096-character schema limit bites first	No — split the input
`401`	`invalid_api_key`	Missing, malformed, or revoked key	No
`403`	`plan_required`	A second voice clone on an account that has never bought credits	No — top up
`403`	—	`This action requires a signed-in session` — a key on key creation, key reactivation, a payment surface, or personal memory	No
`404`	`model_not_found`	No model in the catalog has that id or alias	No — read `GET /v1/audio/models`
`413`	`content_size_limit_exceeded`	An upload over the route’s cap	No — split the file
`429`	`rate_limit_exceeded`	60 requests a minute in one budget shared by nine routes — see the list, which is wider than “the speech endpoints”	Yes, with backoff
`429`	`free_tier_daily_limit`	The day’s free-tier seconds are spent for that surface	Not today — resets 00:00 UTC, or buy credits
`429`	`insufficient_quota`	Prepaid balance below the minimum	No — top up
`502`	`upstream_unreachable`	The model backend did not answer	Yes, with backoff
`502`	`upstream_auth_misconfigured`	The gateway’s own credentials were refused upstream — never your key	No — report it
`502`	`upstream_protocol_error`	A backend answered with something that is not the contract	Yes, once
`503`	`model_unavailable`	A real model of the right kind, with no backend configured in this deployment	No — pick a served id
`503`	`server_busy`	The transcription upload queue is full, or a slot did not free within 10 s	Yes, with backoff
`503`	`free_tier_daily_limit_unavailable`	The ceiling store could not be read, so cost-bearing work is refused	Yes, shortly

The three 429s need three different responses, and telling them apart is the whole reason they carry distinct codes: rate_limit_exceeded means slow down, free_tier_daily_limit means come back tomorrow or pay, insufficient_quota means pay. Only the first is worth a retry of the same request.

Three ways a model id fails

They are different mistakes and they answer differently, so do not collapse them into one handler.

You sent	Answer
An id no catalog entry has	`404 model_not_found`
A real id to the wrong endpoint — `nur-tts-v1` to `/v1/audio/transcriptions`	`400 model_wrong_kind`
A real id of the right kind, with no backend wired up here	`503 model_unavailable`

Each message lists the ids that would have worked for that endpoint in this deployment, which is usually the whole answer. 503 model_unavailable is a deployment fact rather than a client mistake — nothing you can change in the request fixes it.

/v1/realtime resolves models through the registry directly rather than through that explaining layer, so all three cases arrive there as the single 404 model_not_found — and on the socket, as a 1008 close carrying that message.

WebSocket close codes

A live socket has no status line, so refusals arrive as close codes. The reason carries the first 120 characters of the message.

Code	Means	Retry
`1000`	The server closed deliberately — the session ended	No
`1008`	A limit or a rejection: bad credentials, no such model, quota, free-tier day, rate limit	Later, or not at all — read the reason
`1011`	The realtime backend is unavailable	Not immediately; retrying changes nothing until it is back
`1006`	The connection dropped without a close frame — deploy, network, restart	Yes, with backoff

1008 is the one that carries meaning. It is used for every connect-time refusal: an unresolvable model, a failed credential, an exhausted balance, a spent free day, and the per-minute rate limit.

A limit reached mid-call

The balance and the free-tier day are re-checked once a minute while a session is up, so a call can meet a limit it did not have at connect. Before the 1008, the gateway sends one more eesi.session frame that says why:

{
  "type": "eesi.session",
  "event_id": "event_9f2c...",
  "session_id": "0f0c4a0e-3f5e-4c2a-9c1e-7a6b5d4c3b2a",
  "resume": { "supported": false, "reason": "free_tier_daily_limit" },
  "limit": {
    "code": "free_tier_daily_limit",
    "message": "Daily free-tier limit reached for realtime (900 seconds of conversation per day). It resets at 00:00 UTC."
  }
}

Show limit.message. A client that ignores this frame tells the person “connection lost”, which is both wrong and unactionable. Note that resume.supported is false on it. Drop the handle rather than redialling with it — the connect-time gate would refuse the resume for the same reason, and a redial loop against a spent balance is the failure mode this frame exists to prevent. Only insufficient_quota and free_tier_daily_limit end an established session this way; a re-check that could not decide — because the ledger or the ceiling store was unreachable — refuses a new session but never cuts one that is already up.

What is worth retrying

Retry with backoff: 429 rate_limit_exceeded, 502, 503, and a 1006 close. These are conditions that clear on their own. Do not retry: anything 4xx that names a fix — a bad voice id, an unknown model, a validation failure, an exhausted balance. Retrying a 429 insufficient_quota in a loop is how an outage becomes a rate-limit ban on top of an outage. Never retried for you: the SDKs retry a GET once on a connection failure and nothing else, because a POST that failed on the wire may still have reached the server. A retried voice clone is a second 100-credit charge; a retried synthesis is a second bill. Retry a write only when you know it is safe to repeat.

Reading an error in code

from eesi_sdk import EESIClient
from eesi_sdk.errors import ApiError

RETRYABLE = {"rate_limit_exceeded", "upstream_unreachable", "session_store_unavailable"}

with EESIClient() as client:
    try:
        client.create_speech(body={"model": "nur-tts-v1", "voice": "nope", "input": "hi"})
    except ApiError as error:
        if error.code in RETRYABLE or error.status_code in (502, 503):
            ...  # back off and try again
        elif error.code == "insufficient_quota":
            ...  # stop, and tell someone to top up
        else:
            raise

import { EESIClient, ApiError } from "@eesi/sdk";

const RETRYABLE = new Set([
  "rate_limit_exceeded",
  "upstream_unreachable",
  "session_store_unavailable",
]);

const client = new EESIClient();

try {
  await client.createSpeech({
    body: { model: "nur-tts-v1", voice: "nope", input: "hi" },
  });
} catch (error) {
  if (error instanceof ApiError) {
    if (RETRYABLE.has(error.code ?? "") || error.statusCode >= 502) {
      // back off and try again
    } else if (error.code === "insufficient_quota") {
      // stop, and tell someone to top up
    } else {
      throw error;
    }
  } else {
    throw error;
  }
}

ws.onclose = (event) => {
  if (event.code === 1008) {
    // A limit or a rejection. `limitNotice` is whatever arrived on the last
    // eesi.session frame carrying `limit`.
    show(limitNotice?.message ?? event.reason ?? "The session was refused.");
  } else if (event.code === 1011) {
    show("The realtime service is unavailable. Try again in a few minutes.");
  } else if (event.code === 1006) {
    reconnectWithBackoff(); // and mint a fresh ticket
  }
};

Pricing and limits

The ceilings behind every 429.

Connections that survive

Close codes, keepalives and resumption in full.

Authentication

What a 401 or a 403 on a key actually means.

SDKs

ApiError, its fields, and the retry policy.

Build

Cookbook

Billing

Two envelopes

HTTP status and code

Three ways a model id fails

WebSocket close codes

A limit reached mid-call

What is worth retrying

Reading an error in code

Next

Pricing and limits

Connections that survive

Authentication

SDKs

​Two envelopes

​HTTP status and code

​Three ways a model id fails

​WebSocket close codes

​A limit reached mid-call

​What is worth retrying

​Reading an error in code

​Next

Pricing and limits

Connections that survive

Authentication

SDKs

Two envelopes

HTTP status and code

Three ways a model id fails

WebSocket close codes

A limit reached mid-call

What is worth retrying

Reading an error in code

Next