REST API ↗
API reference

Errors

Every failure inside the core is thrown as a DialogueError with a stable code. What the hooks expose, though, is the lighter error EVENT payload — mind the difference.

Two shapes: the class vs. the event

The core throws a DialogueError (the full class). The event bus and hooks surface the lighter error event payload — just { code, message, recoverable }. useInterview().error is that payload, not the class, so it has no status or raw.

ts
import { isDialogueError, type DialogueError, type ErrorCode } from '@dialogueai/react';

// 1. The class — what the core throws (and what isDialogueError() narrows to).
//    DialogueError extends Error with:
//      code: ErrorCode          // stable, switch on this
//      recoverable: boolean     // can retry() help?
//      status?: number          // HTTP status, if any
//      raw?: unknown            // original payload

// 2. The event payload — what hooks/onError/the bus give you (no status/raw):
type DialogueErrorEvent = { code: ErrorCode; message: string; recoverable: boolean };
Use isDialogueError(e) only on values you catch from a thrown core call (e.g. a rejected submit()). For lifecycle errors, read useInterview().error / onError and switch on .code.

Handling errors

tsx
const { phase, error, retry } = useInterview(studyId);

if (phase === 'errored' && error) {
  return (
    <div>
      <p>{error.message}</p>
      {error.recoverable && <button onClick={retry}>Try again</button>}
    </div>
  );
}
Only recoverable codes (the ✓ column below) respond to retry(). Everything else needs a remount or a fixed config/embed.

Remediation playbooks

The blockers integrators hit most often, and what actually fixes each:

CodeFix
permission.policy-blockedYou are inside an iframe without media permissions. Add allow="camera; microphone; display-capture" to the iframe, and serve over HTTPS. Not recoverable from inside the SDK — the host embed must change.
webrtc.blocked-by-networkA corporate firewall or VPN is blocking UDP/TURN. Ask the participant to switch networks; there is no client-side retry that fixes a blocked network.
host.csp-blocks-livekitAdd the LiveKit signaling/media origins to the host page's Content-Security-Policy (connect-src + media-src). A same-origin proxy does not help here — WebRTC needs the real origins.
config.already-open-elsewhereAnother interview instance is mounted. Tear it down (unmount the provider / Dialogue("destroy")) before opening a new one. Recoverable via retry() once the other instance is gone.
config.screen-share-unavailableThe study requires screen share but the browser/context cannot provide it (no getDisplayMedia, or a blocking permissions policy). There is no fallback — the participant needs a supported browser.
auth.origin-not-allowedThe page origin is not on the key allow-list. Add it in the Dialogue dashboard. This is a config fix, not a retry.

Error codes

auth

CodeMeaningRecoverable
auth.invalid-publishable-keyThe publishable key was rejected.
auth.bootstrap-failedBootstrap token exchange failed.
auth.bootstrap-token-expiredThe bootstrap token had already expired.
auth.invalid-bootstrap-tokenThe bootstrap token was malformed or rejected.
auth.origin-not-allowedThe current origin is not allow-listed for this key.
auth.token-refresh-failedA session-token refresh failed.

study

CodeMeaningRecoverable
study.not-foundNo study matches the studyId.
study.pausedThe study is paused.
study.quota-exceededThe study has hit its participant quota.
study.not-activeThe study is not currently accepting participants.
study.already-completedThis participant already completed the study.

permission / device

CodeMeaningRecoverable
permission.camera-deniedCamera permission was denied.
permission.microphone-deniedMicrophone permission was denied.
permission.screen-share-deniedScreen-share permission was denied.
permission.camera-not-readableThe camera is in use or unreadable.
permission.microphone-not-readableThe microphone is in use or unreadable.
permission.camera-overconstrainedNo camera satisfies the constraints.
permission.policy-blockedA permissions policy blocked media (e.g. iframe allow=).
device.no-camera-foundNo camera device is available.
device.no-microphone-foundNo microphone device is available.

webrtc / host

CodeMeaningRecoverable
webrtc.connection-failedThe WebRTC connection could not be established.
webrtc.blocked-by-networkNetwork/firewall blocked the media connection.
webrtc.disconnected-unrecoverableThe connection dropped unrecoverably.
host.csp-blocks-livekitThe host page's CSP blocks the LiveKit endpoint.

config / internal

CodeMeaningRecoverable
config.publishable-key-and-init-mismatchinit() called twice with a different config.
config.already-open-elsewhereAn interview is already open elsewhere.
config.screen-share-unavailableScreen share is required but unavailable.
interview.studyId-lockedThe studyId cannot change after creation.
internal.unknownAn unexpected error.
internal.contract-mismatchA response did not match the expected contract.