SfSkills Domains Docs GitHub

Home / omnistudio / omnistudio-error-handling-patterns

omnistudio-error-handling-patterns

Use when designing fault behavior across Integration Procedures, DataRaptors, OmniScripts, and FlexCards — error routing, user-facing messaging, retry semantics, and idempotency. Triggers: 'omnistudio error', 'integration procedure fault'. NOT for general Apex exception design or Flow fault paths — use data/omnistudio-metadata-management.

Open the skill folder on GitHub

OmniStudio Error Handling Patterns

OmniStudio components fail in more ways than they succeed — callouts time out, DataRaptors hit governor limits, OmniScripts abandon mid-flow, FlexCard actions return errors the card ignores. The default behavior across these tools is to surface a generic "An error occurred" or — worse — to silently complete with empty data. Good error handling across OmniStudio means naming each failure boundary, deciding who catches it, and deciding what the user sees.

Integration Procedures are the first and most important error boundary. They compose Apex, DataRaptors, HTTP actions, and conditional steps, and every one of those can fail. IP steps have a Fail On Step Error flag and a Response Action branch — both must be set deliberately. An IP that leaves these defaults often swallows downstream failures and returns a 200 with incomplete data.

DataRaptors are the second boundary. Extract operations that hit SOQL governor limits will throw; Load operations that violate validation rules surface field-level errors. Unless the caller inspects the response, these are lost.

OmniScripts sit closest to the user. They should translate technical errors into business-readable messages, let the user retry where safe, and preserve filled-in data so the user is not punished for a transient failure.

Before Starting

Core Concepts

Failure Boundaries

  1. HTTP Action — callout failures, timeouts, non-2xx responses.
  2. DataRaptor — governor limits, validation errors, mapping failures.
  3. Integration Procedure — any step can bubble; IP-level Response Action decides routing.
  4. OmniScript step — action returns an error; step can branch to a fault screen or loop back.
  5. FlexCard action — action handler returns a fault; card decides whether to show error state or silently fail.

Response Action Routing

Every IP step has four relevant controls:

Setting these to "Terminate on Error" for downstream-critical steps and explicit continue for best-effort steps is the difference between a resilient IP and a silent one.

Idempotency Contract

Any IP that writes must be idempotent at the callout or the caller must track attempts. Use an external ID, a correlation ID in the payload, or a DataRaptor load that treats upsert + external ID as its signature.

Common Patterns

Pattern 1: Fail-Fast IP With User-Facing Fault Screen

Critical write steps terminate the IP on error. The OmniScript inspects the IP response envelope and branches to a fault screen that summarizes what failed, what was saved, and what the user should do next.

Pattern 2: Best-Effort Enrichment Step

An enrichment step (e.g. fetching a nice-to-have third-party score) is marked Continue on Error with a default value. The consumer treats missing enrichment as normal.

Pattern 3: Retry With Correlation ID

HTTP actions write a correlation ID into the payload. On a retryable failure (timeout, 502, 503), the OmniScript allows the user to retry — the downstream system deduplicates by correlation ID.

Pattern 4: Compensating DataRaptor Load

A multi-step write that can partially succeed uses a compensating DataRaptor load on failure to roll back committed records, or flags them for async cleanup.

Pattern 5: Explicit User Messages

Every recoverable failure maps to a business-readable message and an action the user can take. Unrecoverable failures go to a support pathway (case creation, hotline, Slack channel) with enough diagnostic data attached.

Decision Guidance

SituationRecommended ApproachReason
Step is critical to downstream data integrityTerminate on Error + fault screenAvoid half-written records
Step is enrichment onlyContinue on Error + default valueDo not block user for nice-to-have
Downstream system is idempotent-by-external-idRetry enabled, correlation ID in payloadSafe user-initiated retry
Write spans multiple systemsCompensating DataRaptor or async cleanupPartial success is the default
User reaches unrecoverable stateFault screen + support escalationDo not strand the user

Review Checklist

  1. Inventory components — IPs, DRs, OmniScripts, FlexCard actions.
  2. Classify each step as critical or best-effort.
  3. Set Fail On Step Error and Response Action accordingly.
  4. Write the user-facing fault surface and the support escalation path.
  5. Add correlation IDs and idempotency checks to every writable callout.
  6. Validate with negative-path test runs.

Salesforce-Specific Gotchas

  1. IP step defaults silently swallow failures — unset defaults must be corrected per step.
  2. DataRaptor Extract returns empty-but-OK on row-level failures.
  3. OmniScript navigation to "fault step" does not preserve user-entered data unless you wire it.
  4. FlexCard On Failure branches are often left empty in auto-generated actions.
  5. Retried HTTP actions without correlation IDs produce duplicate writes downstream.

Proactive Triggers

Output Artifacts

ArtifactDescription
Fault routing tablePer-step Fail On + Response Action + user message
Retry and idempotency designCorrelation ID strategy
Compensating action planRollback or async cleanup per partial-success scenario

Package files