> ## Documentation Index
> Fetch the complete documentation index at: https://docs.talview.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Reference

> The Proview SDK error object, error codes, and how to handle each one

Every failure the SDK reports — from any module — arrives as a `ProviewError` through the global [`Proview.onError`](/sdk/getting-started#global-error-handling) handler.

```js theme={null}
Proview.onError(function (err) {
  console.error(err.code, err.type, err.message);
});
```

## The error object

```ts theme={null}
interface ProviewError {
  code: string;
  type: ErrorType;
  message: string;
  validationErrors?: CustomValidationError;
}
```

| Field              | Type                                 | Description                                                                                                     |
| ------------------ | ------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
| `code`             | `string`                             | Stable identifier for the failure. See [Error codes](#error-codes).                                             |
| `type`             | `'critical' \| 'warning' \| 'info'`  | Severity. See [Error types](#error-types).                                                                      |
| `message`          | `string`                             | Human-readable reason. Intended for logs and developers — not for display to candidates or reviewers.           |
| `validationErrors` | `CustomValidationError` *(optional)* | Present only when a configuration object failed schema validation. See [Validation errors](#validation-errors). |

## Error types

```ts theme={null}
enum ErrorType {
  CRITICAL = 'critical',
  WARNING  = 'warning',
  INFO     = 'info',
}
```

| Type       | Meaning                                                                               | What you should do                                                                                                                    |
| ---------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `critical` | Core functionality is impacted. Proctoring or playback cannot be delivered correctly. | Stop the flow. Tell the user something is wrong and route them to support. Do not let an assessment continue as if it were proctored. |
| `warning`  | Something failed but the SDK carried on.                                              | Log it and send it to your monitoring system. No user-facing message.                                                                 |
| `info`     | Informational signal, not a failure.                                                  | Log only.                                                                                                                             |

Severity is decided per occurrence, so the same `code` can arrive as `critical` in one situation and `warning` in another. Read `type` on every error rather than assuming a fixed severity per code.

## Error codes

```ts theme={null}
enum ErrorCode { … }
```

<Note>
  The playback module raises its own codes instead of these — see [Playback → Errors](/sdk/session/playback#errors).
</Note>

### Session

| Code                     | Fires when                                                                                                                                                  |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `MISSING_REQUIRED_FIELD` | A required identifier or field was not supplied to `init` or a session method.                                                                              |
| `NO_ACTIVE_SESSION`      | `stop`, `complete`, `pause`, or `resume` was called when no session is running.                                                                             |
| `INVALID_SESSION_STATE`  | The operation is not legal from the session's current state — for example resuming a session that was never paused. The message includes the current state. |

### API

| Code            | Fires when                                                                            |
| --------------- | ------------------------------------------------------------------------------------- |
| `API_ERROR`     | The Talview API was reached but returned an error response.                           |
| `NETWORK_ERROR` | The request never reached the API — offline, DNS failure, CORS, or a blocked request. |

### Authentication

| Code           | Fires when                                                                                                |
| -------------- | --------------------------------------------------------------------------------------------------------- |
| `AUTH_ERROR`   | The credential could not be validated — a malformed, expired, or rejected token.                          |
| `UNAUTHORIZED` | The caller authenticated successfully but is not permitted to perform the operation or view the resource. |

### Resource

| Code                   | Fires when                                                                                      |
| ---------------------- | ----------------------------------------------------------------------------------------------- |
| `RESOURCE_NOT_FOUND`   | The referenced resource does not exist — for example a session UUID that is not in the project. |
| `RESOURCE_UNAVAILABLE` | The resource exists but cannot be served right now.                                             |

### Configuration

| Code             | Fires when                                                                                   |
| ---------------- | -------------------------------------------------------------------------------------------- |
| `CONFIG_ERROR`   | The initialization configuration is missing, or is present but could not be used.            |
| `INVALID_CONFIG` | The configuration failed schema validation. Read `validationErrors` for the specific fields. |

## Known messages

The SDK ships fixed message strings for the codes below.

| Code                     | Message                                                        |
| ------------------------ | -------------------------------------------------------------- |
| `MISSING_REQUIRED_FIELD` | `Attendee id or identifier is required`                        |
| `MISSING_REQUIRED_FIELD` | `Workflow id or identifier is required`                        |
| `MISSING_REQUIRED_FIELD` | `Session identifier is required`                               |
| `MISSING_REQUIRED_FIELD` | `Missing required field: dsn`                                  |
| `NO_ACTIVE_SESSION`      | `No active session found to stop`                              |
| `NO_ACTIVE_SESSION`      | `No active session found to complete`                          |
| `NO_ACTIVE_SESSION`      | `No active session found to pause`                             |
| `NO_ACTIVE_SESSION`      | `No active session found to resume`                            |
| `INVALID_SESSION_STATE`  | `Session cannot be paused. Current state: <state>`             |
| `INVALID_SESSION_STATE`  | `Session cannot be resumed. Current state: <state>`            |
| `INVALID_SESSION_STATE`  | `Session identifier cannot be updated. Current state: <state>` |
| `CONFIG_ERROR`           | `Initialization config is required`                            |
| `CONFIG_ERROR`           | `Invalid configuration provided`                               |

For the remaining codes the `message` comes from the underlying failure — an API response body, a network error — rather than from this catalogue.

<Warning>
  These strings are for reading logs. Do not compare against them in code: wording can change in any release, and a `message` check that silently stops matching is very hard to spot. Use `code`, which is stable.
</Warning>

## Validation errors

When a configuration object fails schema validation, the SDK attaches `validationErrors`:

```ts theme={null}
interface CustomValidationError {
  issues: unknown[];
  formattedMessage: string;
}
```

| Field              | Type        | Description                                                                                                                                                                        |
| ------------------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `formattedMessage` | `string`    | Every validation failure rendered into a single human-readable string, naming the fields that were rejected. **Use this.**                                                         |
| `issues`           | `unknown[]` | Raw output from the SDK's schema validator, one entry per failed field. The element shape is not currently part of the documented contract — treat it as opaque diagnostic detail. |

<Note>
  `validationErrors` is a single object, not an array.
</Note>

```js theme={null}
Proview.onError(function (err) {
  if (err.validationErrors) {
    console.error('Config rejected:', err.validationErrors.formattedMessage);
  }
});
```

## Handling errors

Register one handler before `Proview.init()`, then switch on `code`:

```js theme={null}
Proview.onError(function (err) {
  // Always record the error, whatever it is
  logToMonitoring({
    code: err.code,
    type: err.type,
    message: err.message,
    validation: err.validationErrors && err.validationErrors.formattedMessage,
  });

  switch (err.code) {
    case 'CONFIG_ERROR':
    case 'INVALID_CONFIG':
    case 'MISSING_REQUIRED_FIELD':
      // Integration bug — the values your app passed are wrong.
      // Fix at the source; retrying will not help.
      break;

    case 'AUTH_ERROR':
    case 'UNAUTHORIZED':
      // Credential rejected or insufficient. Fetch a fresh token and
      // re-initialize; if it fails again, the user lacks access.
      break;

    case 'NETWORK_ERROR':
      // Transient. Surface a connectivity message and allow a retry.
      break;

    case 'API_ERROR':
    case 'RESOURCE_UNAVAILABLE':
      // Server-side. Retry with backoff, then escalate.
      break;

    case 'RESOURCE_NOT_FOUND':
      // The identifier is wrong or the resource was removed. Do not retry.
      break;

    case 'NO_ACTIVE_SESSION':
    case 'INVALID_SESSION_STATE':
      // Your app and the SDK disagree about session state.
      // Re-read the session state before issuing the next command.
      break;
  }

  if (err.type === 'critical') {
    showUserNotification('A technical issue occurred. Please contact support.');
  }
});
```

<Warning>
  `Proview.onError` supports a **single** handler — registering a new one replaces the previous. If several parts of your app need to react to SDK errors, fan out from inside one handler rather than calling `onError` again.
</Warning>

Errors thrown inside your own callbacks are swallowed by the SDK so they cannot disrupt core functionality — they do **not** reach `onError`. Wrap callback bodies in their own `try`/`catch`. See [Best Practices](/sdk/best-practices#error-handling).