# Smart Embed error handling

<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

Zoom Contact Center Smart Embed uses different error handling patterns depending on the type of event.

## Client-side validation errors

The `zcc-error` event fires for client-side validation failures before a request reaches the Smart Embed backend.

```javascript
{
    type: "zcc-error",
    data: {
        code: ERROR_CODE, // e.g., "invalid-input"
        message: ERROR_MESSAGE
    },
};
```

For transfer and conference events, errors are returned on the operation-specific response event, such as `zcc-transfer-engagement-response`, with `status: false` instead of using this generic error event.

## Transfer and conference error handling

Transfer and conference events use a unified error handling pattern. These events include `zcc-transfer-engagement`, `zcc-add-call`, `zcc-complete-transfer`, `zcc-merge-consult`, and `zcc-cancel-consult`.

Unlike client-side validation failures that trigger the generic `zcc-error` event, these events return both success and failure results on the **same response event**, for example `zcc-transfer-engagement-response`.

### Response pattern

Every transfer and conference response event includes a `status` field.

-   **Success** - `status` is `true` with operation-specific fields like `consultState`, `destinationSummary`, `holdState`
-   **Failure**- `status` is `false` with additional `errorCode`, `error`, and `message` fields

### Common response fields

All transfer and conference response events share base fields.

| Field                    | Type    | Details                                                                                                                   |
| ------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------- |
| `status`                 | boolean | `true` on success, `false` on failure                                                                                     |
| `requestId`              | string  | Echoes the request's `requestId`                                                                                          |
| `engagementId`           | string  | Active voice engagement ID                                                                                                |
| `channelType`            | string  | Always `"voice"`                                                                                                          |
| `taskSid`                | string  | Internal task ID of the active call                                                                                       |
| `conferenceId`           | string  | Conference ID when the call is in a conference                                                                            |
| `transferType`           | string  | `"direct"` or `"warm"` (when applicable)                                                                                  |
| `timestamp`              | number  | Epoch milliseconds when the response was built                                                                            |
| `holdState`              | boolean | Current hold state of the active leg                                                                                      |
| `consultState`           | string  | One of: `initiated`, `ringing`, `answered`, `bridged`, `completed`, `cancelled`, `merged`                                 |
| `destinationSummary`     | object  | Normalized target with `kind` (`user`, `queue`, `flow`, `pstn`, `unknown`), `id`, `name`, `queueId`, `queueName`, `value` |
| `transferId`             | string  | Transfer identifier (when provided by backend)                                                                            |
| `inviter_leg_channel_id` | string  | Channel identifier (when provided by backend)                                                                             |
| `errorCode`              | string  | Failure only. Indicates the specific error type                                                                           |
| `error`                  | string  | Failure only. Human-readable error message                                                                                |
| `message`                | string  | Failure only. Same as `error` field                                                                                       |

### Common error codes

Transfer and conference events may return error codes.

-   `engagement-mismatch` - Provided engagement ID does not match the active engagement
-   `no-active-call` - No active voice call found for the engagement
-   `unsupported-destination` - The destination format or type is not supported
-   `transfer-failed` - Transfer operation failed
-   `add-call-failed` - Adding consult or conference leg failed
-   `add-call-panel-missing` - Required UI panel is not available
-   `no-active-warm-transfer` - No warm transfer in progress to complete
-   `complete-transfer-failed` - Completing the warm transfer failed
-   `no-active-conference-consult` - No conference consult leg to merge
-   `merge-consult-failed` - Merging the conference failed
-   `no-active-consult` - No active consult leg to cancel
-   `cancel-consult-target-missing` - Consult target information is missing
-   `cancel-consult-failed` - Canceling the consult failed

### Error response example

This example shows the `unsupported-destination` error.

```javascript
{
    type: "zcc-transfer-engagement-response",
    data: {
        status: false,
        requestId: REQUEST_ID,
        engagementId: ENGAGEMENT_ID,
        channelType: "voice",
        taskSid: TASK_SID,
        conferenceId: CONFERENCE_ID,
        transferType: "warm",
        timestamp: TIMESTAMP_MS,
        holdState: false,
        consultState: "initiated",
        errorCode: "unsupported-destination",
        error: "The specified destination is not supported",
        message: "The specified destination is not supported",
    },
}
```