---
title: "Embedded UI Error Surfacing Reference"
slug: "embedded-ui-error-surfacing-reference"
tags: ["embedded-ui", "reference-guides"]
status: "update"
updated: 2026-10-13T18:18:53Z
published: 2026-10-13T18:18:53Z
canonical: "docs.unqork.io/embedded-ui-error-surfacing-reference"
---

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

# Embedded UI Error Surfacing Reference

This reference documents the error surfacing architecture, error types, and payload format. Errors occurring inside the embedded module, including HTTP failures, Angular exceptions, routing errors, and workflow navigation failures, are surfaced to the host application through two parallel channels.

## Channels

When an error occurs inside an embedded module, the Embedded UI sends the error payload to the host page through one or both of these channels at the same time. You can listen on either or both.

| Channel | Usage | Description |
| --- | --- | --- |
| CustomEvent | `window.addEventListener('unqork-embed-error', handler)` | Recommended. The handler receives the error payload in `event.detail`. Use this pattern to handle errors the same way you handle other browser events. |
| Bridge Handler | `window.__UNQORK_EMBED_ERROR_HANDLER__ = handler` | An alternative global callback. Set this property on `window` before mounting any modules, and it will be called with the same payload as the CustomEvent. |

Both channels receive the same error payload. The system does nothing when running outside of embedded mode.

## Architecture

The diagram below shows how errors flow from their source, through an optional enrichment layer, to the host application. Module errors pass through `surfaceError()` to pick up a `moduleId`. Workflow errors skip that layer and go directly to `surfaceEmbedError()`.

![Diagram](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/api_upload_20261013_181852_4767f0399c184592bbb062b65d2d9d7f.svg?sv=2026-02-06&spr=https&st=2026-11-08T04%3A04%3A42Z&se=2026-11-08T05%3A04%3A42Z&sr=c&sp=r&sig=J0KaOsI4gwvP6QGeGoPxkKJOFXF8d%2B6weQF9hctoRGc%3D)

## Two-Layer Design

The error surfacing system is split into two functions with different responsibilities. The core broadcaster dispatches errors to the host page. The enrichment layer adds context before dispatching.

### `surfaceEmbedError()` - Core Broadcaster

The shared, stateless utility function in `embed-utils.js`. It dispatches the `unqork-embed-error` CustomEvent on `window` and calls the bridge handler if one is set. This function does nothing when the code is running outside of embedded mode.

### `surfaceError()` - Enrichment Layer

A thin wrapper function in `spa-embed.js` that adds the current `moduleId` to an error before passing it to `surfaceEmbedError()`. All Angular interceptors and decorators in `spa-embed.js` call this function instead of calling `surfaceEmbedError()` directly.

### Direct `surfaceEmbedError()` Calls

Workflow-specific errors in `displayWorkflow.js` call `surfaceEmbedError` directly, enriching with `workflowPath`, `stepPath`, and `action` instead of `moduleId`.

## Error Types

The table below lists every error type the system can emit. Each type corresponds to a different failure mode inside the embedded module. The **Emitted By** column shows which function dispatches the error, and the **Context Fields** column lists the additional fields included in the payload for that type.

| Type | Source | Emitted By | Context Fields |
| --- | --- | --- | --- |
| `http` | HTTP interceptor (4xx/5xx) | `surfaceError` | `moduleId`, `url`, `status`, `statusText` |
| `angular` | `$exceptionHandler` decorator | `surfaceError` | `moduleId`, `message`, `originalError` |
| `routing` | `$stateChangeError`, `$stateNotFound` | `surfaceError` | `moduleId`, `toState`, `fromState` |
| `template` | `$templateRequest` failure | `surfaceError` | `moduleId`, `message` (template ) |
| `workflow` | `DisplayWorkflow.error()` | `surfaceEmbedError` | `workflowPath`, `stepPath`, `status` |
| `workflow-fatal` | `DisplayWorkflow.handleError()` | `surfaceEmbedError` | `workflowPath`, `stepPath` |
| `workflow-navigation` | `onWorkflowNavigate()` catch | `surfaceEmbedError` | `workflowPath`, `stepPath`, `action` |

## Error Payload Shape

Every error dispatched through the system includes the base fields below. Additional fields depend on the error type.

### Base Fields

| Field | Type | Description |
| --- | --- | --- |
| `timestamp` | `string` | ISO 8601 timestamp indicating when the error occurred. |
| `type` | `string` | The error category. See the [Error Types](/unqorkai/docs/embedded-ui-error-surfacing-reference#error-types) table for all possible values. |
| `message` | `string` | A human-readable description of the error. |
| `originalError` | `any` | The original error object thrown by the runtime. Useful for debugging. |

### Per-Type Payloads

#### `http`

Dispatched when an API request returns a 4xx or 5xx status.

| Field | Type | Description |
| --- | --- | --- |
| `moduleId` | `string` | MongoDB ObjectId of the module where the error occurred. |
| `url` | `string` | The request URL that returned an error. |
| `status` | `number` | HTTP status code returned by the server. |
| `statusText` | `string` | HTTP status text returned by the server. |

#### `angular`

Dispatched when an unhandled AngularJS runtime exception is caught by the `$exceptionHandler` decorator.

| Field | Type | Description |
| --- | --- | --- |
| `moduleId` | `string` | MongoDB ObjectId of the module where the error occurred. |

#### `routing`

Dispatched when a UI-Router state transition fails.

| Field | Type | Description |
| --- | --- | --- |
| `moduleId` | `string` | MongoDB ObjectId of the module where the error occurred. |
| `toState` | `object` | The target UI-Router state the application failed to reach. |
| `fromState` | `object` | The source UI-Router state the application was leaving. |

#### `template`

Dispatched when an AngularJS template request fails to load.

| Field | Type | Description |
| --- | --- | --- |
| `moduleId` | `string` | MongoDB ObjectId of the module where the error occurred. |

#### `workflow`

Dispatched when the workflow API returns an error status.

| Field | Type | Description |
| --- | --- | --- |
| `workflowPath` | `string` | Workflow path identifier, like `insurance-onboarding`. |
| `stepPath` | `string` | Path of the current workflow step. |
| `status` | `number` | HTTP status code from the workflow API response. |

```json
{
  "timestamp": "2026-06-11T12:00:00.000Z",
  "type": "workflow",
  "message": "Workflow error",
  "workflowPath": "insurance-onboarding",
  "stepPath": "step-1",
  "status": 500,
  "originalError": {}
}
```

#### `workflow-fatal`

Dispatched when a fatal error prevents further workflow processing. Also triggers an error dialog inside the embedded module.

| Field | Type | Description |
| --- | --- | --- |
| `workflowPath` | `string` | Workflow path identifier. |
| `stepPath` | `string` | Path of the current workflow step. |

```json
{
  "timestamp": "2026-06-11T12:00:00.000Z",
  "type": "workflow-fatal",
  "message": "Workflow error: An error has occurred",
  "workflowPath": "insurance-onboarding",
  "stepPath": "step-1",
  "originalError": {}
}
```

#### `workflow-navigation`

Dispatched when a step transition (Next, Previous, or a direct jump) fails. This is separate from the `unqork-embed-workflow-navigate` success event, which fires only on successful navigation.

| Field | Type | Description |
| --- | --- | --- |
| `workflowPath` | `string` | Workflow path identifier. |
| `stepPath` | `string` | Path of the step the end-user was on when navigation failed. |
| `action` | `string` | The navigation action that failed: `next`, `previous`, or `goto`. |

```json
{
  "timestamp": "2026-06-11T12:00:00.000Z",
  "type": "workflow-navigation",
  "message": "Workflow navigation failed (next)",
  "workflowPath": "insurance-onboarding",
  "stepPath": "step-1",
  "action": "next",
  "originalError": {}
}
```

## Error Flow Diagrams

The diagrams below show two common error flows in detail: an HTTP error from a failed API call, and a workflow navigation error when a step transition fails.

### HTTP Error Flow

When an API call inside the module returns a 4xx or 5xx status, the HTTP interceptor catches the response, passes it to `surfaceError()` to attach the `moduleId`, and `surfaceEmbedError()` dispatches it to the host page.

![Diagram](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/api_upload_20261013_181852_743982496177488d88fdd06b83b4afdf.svg?sv=2026-02-06&spr=https&st=2026-11-08T04%3A04%3A42Z&se=2026-11-08T05%3A04%3A42Z&sr=c&sp=r&sig=J0KaOsI4gwvP6QGeGoPxkKJOFXF8d%2B6weQF9hctoRGc%3D)

### Workflow Navigation Error Flow

When an end-user clicks Next and the navigate API call fails, the workflow controller dispatches a `workflow-navigation` error immediately, then a `workflow-fatal` error after it attempts to recover. Both errors reach the host page as separate CustomEvents.

![Diagram](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/api_upload_20261013_181852_86918156b8ea438e8090e13005ae0523.svg?sv=2026-02-06&spr=https&st=2026-11-08T04%3A04%3A42Z&se=2026-11-08T05%3A04%3A42Z&sr=c&sp=r&sig=J0KaOsI4gwvP6QGeGoPxkKJOFXF8d%2B6weQF9hctoRGc%3D)

---

**Changelog**

| Date | Change |
| --- | --- |
| 2026-04-21 | Initial publication. |
| 2026-06-11 | Editorial pass: removed HR dividers, added description paragraphs to all H2/H3 sections and Mermaid diagrams, expanded Channels and Error Types table descriptions for non-expert readers, expanded Error Payload Shape field descriptions, converted surfaceError/surfaceEmbedError H3 format from field/type pattern to prose, updated internal links. |
| 2026-06-15 | Updated Error Types Source column to precise technical labels; restructured Error Payload Shape with base fields and per-type payloads including JSON examples. |

HTTP (Hypertext Transfer Protocol) is an application-layer protocol used to transmit hypermedia documents like HTML.

AngularJS is a JavaScript framework added to an HTML page with a <script> tag. AngularJS extends HTML attributes and binds data to HTML using expressions.

The UI (user interface) is a device's end-user interaction and communication point. It can include display screens, keyboards, and mouse. It is also how a user interacts with your application.

A JavaScript property is a member of an object that associates a key with a value. A JavaScript object is a data structure that stores a collection of properties.

A definition

A standard format for representing dates and times. ISO 8601 format is represented in the following order: year, month, day, hour, minutes, seconds, and milliseconds.

An object is a type of data structure that represents a single, self-contained entity that acts as a container for the characteristics of that entity.

APIs (application programming interfaces) are a set of protocols and definitions developers use to build and integrate application software. APIs act as the connective tissue between products and services.

A URL (uniform resource locator) is a unique identifier used to locate a resource on the internet. Also known as a web address.

HTTP (Hypertext Transfer Protocol) is an application-layer protocol used to transmit hypermedia documents like HTML.

AngularJS is a JavaScript framework added to an HTML page with a

End-users, also known as Express Users, are the individuals accessing an application through Express View. In most cases, end-users are the customers using the product.

An API payload is the data that is sent or received between a client and a server during an API request or response. It contains the information needed to perform actions or get resources.

JSON (JavaScript Object Notation) is an open standard file and data interchange format. Unqork uses JSON for submission (record) data.