SfSkills Domains Docs GitHub

Home / integration / error-handling-in-integrations

error-handling-in-integrations

Use this skill to design orchestration-layer error handling for Salesforce integrations — covering Platform Event replay recovery, dead-letter queue routing, cross-channel error notification patterns, circuit breaker design, and trigger suspension recovery. Triggers: integration error handling, Platform Event retry, integration dead letter queue, circuit breaker. NOT for Apex exception handling — use apex/exception-handling. NOT for HTTP error response contracts — use integration/api-error-handling-design. NOT for retry backoff patterns — use integration/retry-and-backoff-patterns.

Open the skill folder on GitHub

Error Handling in Integrations

This skill activates when a developer or integration architect needs to design orchestration-layer error handling for Salesforce integrations. It covers Platform Event trigger suspension recovery, dead-letter queue patterns, circuit breaker design, and cross-channel failure notifications — distinct from single-transaction Apex exception handling and HTTP error response contracts.

Before Starting

Gather this context before working on anything in this domain:

Core Concepts

Platform Event Trigger Suspension and Recovery

Failure escalation path:

  1. EventBus.RetryableException thrown → up to 9 automatic retries
  2. After 9 failures: trigger suspended — all new events stop processing
  3. Re-enable: Setup > Platform Events > [Event] > Subscribe Triggers > Resume
  4. Set Replay ID on re-enable to replay missed events from the 72-hour window

Recovery requires: knowing the last successfully processed Replay ID (must be stored by the subscriber), fixing the root cause, then resuming with replay from the correct position.

Dead-Letter Queue Pattern

Salesforce has no built-in DLQ. Implement explicitly:

Circuit Breaker

For unstable external systems:

Cross-Channel Notification

Common Patterns

Pattern: RetryableException for Transient, DLQ for Permanent

trigger OrderEventTrigger on OrderEvent__e (after insert) {
    for (OrderEvent__e event : Trigger.new) {
        try {
            OrderIntegrationService.processEvent(event);
            // Store Replay ID on success
            Integration_State__c.getInstance().Last_Replay_Id__c = event.ReplayId;
            update Integration_State__c.getInstance();
        } catch (OrderIntegrationService.TransientException e) {
            // Transient: throw RetryableException for auto-retry
            throw new EventBus.RetryableException('Transient: ' + e.getMessage());
        } catch (Exception e) {
            // Permanent: write to DLQ, do NOT throw RetryableException
            insert new Integration_DLQ__c(
                Event_Type__c = 'OrderEvent',
                Payload__c = JSON.serialize(event),
                Error_Message__c = e.getMessage(),
                Status__c = 'Pending_Retry'
            );
        }
    }
}

Decision Guidance

Failure ScenarioRecommended PatternReason
Transient external error (timeout, 503)RetryableExceptionPlatform auto-retry handles transient failures
Permanent data error (invalid payload)Write to DLQ; no RetryableExceptionRetryableException on permanent errors suspends trigger
External system down > 1 hourCircuit breaker OPEN + DLQ accumulatePrevent cascade failures and API limit exhaustion
Trigger suspendedRecovery runbook: Replay ID re-enable72-hour window enables recovery
Silent failures not visible to opsCross-channel notification platform eventOps must know about failures immediately
  1. Identify the integration pattern (Platform Events, REST, CDC, Bulk API) — each has different failure modes.
  2. For Platform Event subscribers: implement RetryableException for transient errors only; DLQ for permanent failures.
  3. Implement Replay ID tracking: store last successful Replay ID in a Custom Setting on every successful event.
  4. Design DLQ object schema and Scheduled Apex retry job with configurable max retry count.
  5. Design cross-channel notification: Platform Event for failures → Flow Email + Slack + Case creation based on severity.
  6. For unstable external systems: implement circuit breaker using Custom Setting for failure count and circuit state.
  7. Document the trigger suspension recovery runbook in team operations documentation.

Review Checklist

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

  1. Trigger suspension affects ALL events — not just the failing ones — Suspending a Platform Event trigger blocks all new events on that channel until manually re-enabled. One bad payload can halt all integration processing.
  2. Replay ID is unstable after Salesforce maintenance — Replay IDs can become stale after maintenance. Store the event message ID for deduplication; use Replay ID only for starting the replay position.
  3. RetryableException on permanent errors suspends the trigger faster — Throwing RetryableException on a permanent failure wastes all 9 retries on a record that will never succeed, then suspends the trigger. Only use RetryableException for genuinely transient errors.

Output Artifacts

ArtifactDescription
DLQ schema and retry jobIntegration_DLQ__c design and Scheduled Apex pattern
Trigger suspension recovery runbookSteps to re-enable and replay after trigger suspension
Circuit breaker designCustom Setting schema and state-transition logic
Cross-channel notification designError event → notification channel mapping

Package files