Errors: Every Code and What To Do

Every error has a short, stable code. Branch on the code; show or log the message. Codes do not change between releases, messages may be reworded.

A blurry or frozen picture, echo, or a camera the browser will not open is not on this page: those come from the device or the network rather than from an error code. Troubleshooting shows how to tell which, and what to do, including the browser's own camera errors such as NotAllowedError.

How errors arrive

REST API. The HTTP status and a JSON body:

{ "error": "quota-exhausted", "message": "this account has used all of its minutes" }

Realtime connection. The reply to the request that failed:

{ "id": 7, "ok": false, "error": { "code": "forbidden", "message": "role viewer may not publish" } }

SDKs. The same code, on a typed error:

From the browser and Flutter SDKs 0.7.0 and the Node.js SDK 0.4.0, every SDK reads one registry of codes shared by all VoltKit SDKs. It says whether a code is terminal (a join refused with it is not retried) and whether retrying can help:

A newer service may send a code an older release does not know. It is passed through unchanged and is never treated as terminal.

// Node.js
try {
  await rtc.ensureRoom({ roomId, hostIdentity });
} catch (err) {
  if (err.isOutOfMinutes) return res.status(402).send("Top up to go live");
  if (err.retryable) return retryLater();
  throw err;
}

// Browser
import { RpcError } from "@voltkit-rtc/client";

try {
  await client.sendMessage(text);
} catch (err) {
  if (err instanceof RpcError && err.code === "chat-muted") showMutedNotice();
  else if (err instanceof RpcError && err.code === "rate-limited") showSlowDown();
}

// Flutter
try {
  await client.sendMessage(text);
} on RpcError catch (e) {
  if (e.code == 'chat-muted') showMutedNotice();
}

REST errors

401, 402, 403 and 429 rate-limited can come back from any call.

Realtime errors

Video profile and screen-share errors (SDK 0.5.0)

Browser chooser cancellation can also reject with native NotAllowedError or AbortError; no screen was shared. Camera, microphone and music do not need to be stopped. Host/co-host permissions and server moderation apply to screen capture too; a viewer receives forbidden.

Media settings and wallet billing errors

A project's media settings say what it may publish. The browser and Flutter SDKs 0.7.0 read them when they join and never send what would be refused: they either refuse the call or send the most the project allows and warn, with the same code the server would use. The media server enforces the settings whatever a client sends; the codes it raises itself (marked server) apply to sessions billed from the VoltKit Wallet: every account, unless VoltKit keeps it on minute billing by agreement. Do not retry the same request: publish within the settings instead.

A 30 fps quality above the project's largest is not an error: the SDKs and the server cap it silently.

Codes the SDKs raise themselves

New in the browser and Flutter SDKs 0.7.0 and the Node.js SDK 0.4.0. Warnings arrive on error (browser) or onError and onPublishWarning (Flutter) and stop nothing; refusals reject the call.

When an account runs out mid-session

A live session is not left running when its project runs out. Clients first receive usageLimit with { reason, graceSeconds, endsAt }; about a minute later the session is ended: rooms with roomClosed (its reason is the same code), chat-only connections with a final usageLimit. Then the server closes the connection with WebSocket close code 4003.

Rooms are warned while the minutes and credits a project may spend cover less than about a minute at the current rate: walletLow with remainingSeconds (and usageLimit, for older apps). A recharge in time sends walletLow with cleared: true, and nothing ends. If the credits reach zero, the rooms close at once with roomClosed (reason quota-exhausted) and close code 4003. See Running low and running out.

Why a session ended

When a client's session is over for good, the SDKs say why instead of leaving you to guess:

Broadcast publishing errors

Publishing a broadcast is one HTTP exchange with the media server. A failure is a WhipError:

Still stuck

Send the error code, the time, and your App ID (never your API secret) to contact@voltkit.in, or open a ticket from the Support page of your dashboard. For a quality or connection problem, Troubleshooting lists what to include so we can find your session.