Errors

Cosmo refuses a session in two different places, and the difference decides where you catch it. Anything wrong with the credential, the workspace, or the config is refused at the HTTP layer during session start, before a room exists — the SDKs surface those as start failures. Once a session is live, the server sends error frames over the data channel, each with a code, message, and fatal flag. The SDKs additionally raise typed exceptions for local failures (dialing, sends before connect).

Session-start rejections

These arrive as non-2xx REST responses to the session-start call, carried in the standard error envelope (error.type, error.code, error.message). No room is created, so you never see them as error frames. Catch them where you call start().

Each typed rejection carries a machine-readable error.code to branch on:

Three rejections carry no typed code — branch on the HTTP status instead:

• 401 / 403 — the credential is missing, expired, invalid, lacking the required realtime:* scope, or bound to a workspace this host doesn't serve. Refresh or fix the credential; don't retry with the same one.
• 400 — audio.output: false with a speech-to-speech-only model. Pick a different model or leave audio output on.
• 503 — realtime voice is temporarily unavailable on this deployment. Retry with backoff.

Schema validation runs first: a malformed body — wrong types, out-of-range values, oversize fields — returns 422 validation_error before any typed rejection. The typed codes above fire on well-formed configs.

See POST /session/start for the full status-code table.

Wire error codes

These come over the data channel on a live session (ErrorCode).

The errors a running session can actually receive:

The enum also reserves auth_failed, workspace_forbidden, voice_disabled, and version_mismatch. Those conditions reject the session start over HTTP (above) before a data channel exists, so a live session never receives them — the SDKs still map them, so they would surface as typed errors rather than unknown (see the wire-protocol code table).

What the TypeScript error axis carries

The TypeScript SDK's error event and useRealtimeError() deliver the error itself, not a summary of it. Three things reach them, and null clears the axis:

The first two are RealtimeError subclasses, so instanceof RealtimeError separates them from the server's event, and each names itself in name:

import { RealtimeError } from 'cosmo-ai';

if (error instanceof RealtimeError) {
  switch (error.name) {
    case 'SessionStartError': /* error.code is a SessionStartErrorCode */ break;
    case 'AudioUnavailableError': /* error.code is an AudioUnavailableErrorCode */ break;
  }
} else {
  // The server's event: error.code is the server ErrorCode, error.fatal its fatality.
}

A transport that drops mid-session is reported on the lifecycle axis rather than here: session.state reaches disconnected with disconnectReason: 'transport_error' and the close reason in detail, and the session_ended event fires. A failure on a per-call method — a mic toggle, a dial() — reaches the caller as a rejected promise and does not latch here.

Error subscription

import { SessionStartError } from 'cosmo-ai';

try {
  const session = await client.agent(config).start();
} catch (err) {
  if (!(err instanceof SessionStartError)) throw err;
  switch (err.code) {
    case 'busy':
      // Concurrent-session limit — an abandoned session frees its slot
      // after a short window; offer a retry, after err.retryAfterSeconds
      // when the server sent one.
      break;
    case 'entitlement':
      // Free minutes exhausted, or the plan lacks the model's provider.
      break;
    case 'config':
      // The config was rejected — err.serverCode names the reason.
      break;
    default:
      // err.status and err.detail carry the specifics.
  }
}

import { RealtimeError } from 'cosmo-ai';

session.on('error', (error) => {
  if (error === null) return;  // null = error cleared on recovery
  console.error(`[${error.code}] ${error.message}`);

  if (error instanceof RealtimeError) {
    if (error.name === 'AudioUnavailableError' && error.code === 'mic_denied') {
      // Show mic permission instructions
    }
    return;
  }
  // A live session only receives the codes in the table above; a credential
  // or entitlement refusal never reaches here, because it happens over HTTP
  // before the data channel exists and arrives as a SessionStartError.
  if (error.fatal) {
    // The session is gone — offer a "reconnect" action that starts a new one
  } else {
    // The turn failed; the session continues. Log it and carry on.
  }
});

import { useRealtimeError } from 'cosmo-ai/react';

function ErrorBanner() {
  const error = useRealtimeError();
  if (!error) return null;
  return <div role="alert">{error.message}</div>;
}

from cosmo_ai import (
    DialError,
    SessionStateError,
    ErrorEvent,
    SessionStartError,
)

try:
    async with agent.start() as session:
        async for event in session:
            if isinstance(event, ErrorEvent):
                print(f"[{event.code}] {event.message} (fatal={event.fatal})")
                if event.fatal:
                    break   # the terminal session-ended item follows
except SessionStartError as exc:
    print(f"session start rejected: [{exc.code}] {exc}")

do {
    let session = try await agent.start()
    for try await event in session.events {
        if case .error(let e) = event {
            print("server error [\(e.code.rawValue)] \(e.message) fatal=\(e.fatal)")
            // e.fatal == true → the terminal .sessionEnded follows; start a new session
        }
    }
} catch let error as AudioUnavailableError {
    // The microphone would not open — error.code says which failure it was.
    print("microphone unavailable [\(error.code.rawValue)] \(error.message)")
} catch let error as SessionStartError {
    // error.code is a closed SessionStartErrorCode — .handshakeFailed,
    // .readyTimeout, .busy, … — and error.serverCode the server's own slug.
    print("start failed [\(error.code.rawValue)] \(error.message)")
} catch let error as any ApiError {
    // Any backend call — mint, verify, usage, dial. Catch a specific one
    // (MintTokenError, DialError, …) when you need to know which.
    print("api call failed [\(error.message)] server=\(error.serverCode ?? "-")")
}

fatal flag

fatal: true means the session is dead and can't continue — the stream finishes with its terminal session-ended item; start a new session. fatal: false means this turn or operation failed but the session itself is still alive — you may continue speaking.

Recovery recipes

401 / 403 credential rejections

These are almost always configuration errors. Check:

1. The API key (or minted token) is valid and not expired.
2. The key has the realtime:start scope (the deprecated realtime:use umbrella implies it).
3. The key belongs to the workspace whose agents and tools you're referencing.

upstream_disconnect (non-fatal)

The server attempts a transparent upstream-session rotation. The client receives reconnecting on the data channel; the session and transport survive. If instead the frame was fatal: true, start a new session (optionally with resume_session_id).

version_mismatch

Reserved. Current servers don't send it; if an older server refuses the connection with it, upgrade the SDK. See Protocol compatibility.

invalid_message

If you're using a supported SDK version and not hand-crafting messages, report it as an SDK bug. If you're hand-crafting, validate your messages against the wire protocol reference.

Pitfalls

• The error event in TypeScript fires with null when the error is cleared (for example, on the next session start). Handlers must check for null: if (error === null) return;.
• A mid-session transport drop does not reach the TypeScript error axis. Read session.state (disconnectReason: 'transport_error') or the session_ended event for it.
• The wire ErrorCode is the server enum; a device or permission failure is not in it — that arrives as AudioUnavailableError with an AudioUnavailableErrorCode.
• A non-fatal error never ends the session — don't tear down on every frame. Gate teardown on fatal, the session_ended event, or the lifecycle reaching disconnected.