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.

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().

flowchart TB
    subgraph "Error Sources"
        HTTP["HTTP interceptor (4xx/5xx responses)"]
        ANG["$exceptionHandler (Angular runtime errors)"]
        ROUTE["$stateChangeError (routing failures)"]
        TPL["$templateRequest (template load failures)"]
        WF_ERR["DisplayWorkflow.error() (workflow API errors)"]
        WF_FATAL["DisplayWorkflow.handleError() (workflow fatal errors)"]
        WF_NAV["onWorkflowNavigate catch (navigation failures)"]
    end

    subgraph "Enrichment Layer"
        SE["surfaceError() in spa-embed.js - adds moduleId"]
    end

    subgraph "Core Utility"
        SEE["surfaceEmbedError() in embed-utils.js - dispatches event and calls bridge"]
    end

    subgraph "Host Application"
        EVT["window unqork-embed-error event"]
        BRG["window.__UNQORK_EMBED_ERROR_HANDLER__"]
    end

    HTTP --> SE
    ANG --> SE
    ROUTE --> SE
    TPL --> SE
    SE --> SEE

    WF_ERR --> SEE
    WF_FATAL --> SEE
    WF_NAV --> SEE

    SEE --> EVT
    SEE --> BRG

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.

Error Payload Shape

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

Base Fields

Per-Type Payloads

http

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

angular

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

routing

Dispatched when a UI-Router state transition fails.

template

Dispatched when an AngularJS template request fails to load.

workflow

Dispatched when the workflow API returns an error status.

{
  "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.

{
  "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.

{
  "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.

sequenceDiagram
    participant Module as Angular Module
    participant Interceptor as HTTP Interceptor
    participant SE as surfaceError()
    participant SEE as surfaceEmbedError()
    participant Host as Host Page

    Module->>Interceptor: API call returns 500
    Interceptor->>SE: { type: 'http', status: 500, url }
    SE->>SEE: { moduleId, type: 'http', ... }
    SEE->>Host: CustomEvent('unqork-embed-error')
    SEE->>Host: __UNQORK_EMBED_ERROR_HANDLER__()

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.

sequenceDiagram
    participant User as User clicks Next
    participant DW as DisplayWorkflow
    participant API as Unqork API
    participant SEE as surfaceEmbedError()
    participant Host as Host Page

    User->>DW: next()
    DW->>API: POST /navigate
    API-->>DW: Error response
    DW->>SEE: { type: 'workflow-navigation', action: 'next', workflowPath, stepPath }
    SEE->>Host: CustomEvent('unqork-embed-error')
    DW->>DW: processWorkflowResponse(err) handleError() SweetAlert
    DW->>SEE: { type: 'workflow-fatal', message, workflowPath }
    SEE->>Host: CustomEvent('unqork-embed-error')