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:
- Platform Events retain messages for 72 hours (replay window). The stable deduplication key is the event message ID — not the Replay ID, which can be corrupted after Salesforce maintenance events.
EventBus.RetryableException triggers up to 9 automatic retries before the Platform Event trigger is suspended. A suspended trigger stops processing ALL new events on that channel.
- Existing skills cover related but distinct topics:
integration/retry-and-backoff-patterns covers HTTP retry backoff; integration/api-error-handling-design covers HTTP error response contracts. This skill covers orchestration-layer routing and recovery.
- The most critical mistake: throwing RetryableException for permanent errors (bad data, invalid config) causes 9 retries of a record that will never succeed, then suspends the trigger — blocking all event processing.
Core Concepts
Platform Event Trigger Suspension and Recovery
Failure escalation path:
- EventBus.RetryableException thrown → up to 9 automatic retries
- After 9 failures: trigger suspended — all new events stop processing
- Re-enable: Setup > Platform Events > [Event] > Subscribe Triggers > Resume
- 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:
- Custom object
Integration_DLQ__c with: Source_System__c, Event_Type__c, Payload__c (JSON text), Error_Message__c, Retry_Count__c, Status__c (Pending / Failed_Max_Retries / Resolved)
- Scheduled Apex retries Pending DLQ entries periodically
- After max retries: mark as Failed_Max_Retries and trigger ops notification
Circuit Breaker
For unstable external systems:
- Track consecutive failures in a Custom Setting (failure count + timestamp)
- CLOSED (normal): calls go through
- OPEN (threshold exceeded): skip external call, log OPEN state, notify ops
- HALF_OPEN (after cooldown): attempt one test call; success → CLOSE; failure → OPEN again
Cross-Channel Notification
- Platform Event
Integration_Error__e → Flow → Email Alert for standard failures
- Platform Event → Named Credential callout to Slack webhook for high-severity
- Case creation for SLA-impacting failures requiring human resolution
- CRM Analytics or Lightning report on DLQ volume for operations dashboards
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 Scenario |
Recommended Pattern |
Reason |
| Transient external error (timeout, 503) |
RetryableException |
Platform auto-retry handles transient failures |
| Permanent data error (invalid payload) |
Write to DLQ; no RetryableException |
RetryableException on permanent errors suspends trigger |
| External system down > 1 hour |
Circuit breaker OPEN + DLQ accumulate |
Prevent cascade failures and API limit exhaustion |
| Trigger suspended |
Recovery runbook: Replay ID re-enable |
72-hour window enables recovery |
| Silent failures not visible to ops |
Cross-channel notification platform event |
Ops must know about failures immediately |
Recommended Workflow
- Identify the integration pattern (Platform Events, REST, CDC, Bulk API) — each has different failure modes.
- For Platform Event subscribers: implement RetryableException for transient errors only; DLQ for permanent failures.
- Implement Replay ID tracking: store last successful Replay ID in a Custom Setting on every successful event.
- Design DLQ object schema and Scheduled Apex retry job with configurable max retry count.
- Design cross-channel notification: Platform Event for failures → Flow Email + Slack + Case creation based on severity.
- For unstable external systems: implement circuit breaker using Custom Setting for failure count and circuit state.
- Document the trigger suspension recovery runbook in team operations documentation.
Review Checklist
Salesforce-Specific Gotchas
Non-obvious platform behaviors that cause real production problems:
- 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.
- 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.
- 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
| Artifact |
Description |
| DLQ schema and retry job |
Integration_DLQ__c design and Scheduled Apex pattern |
| Trigger suspension recovery runbook |
Steps to re-enable and replay after trigger suspension |
| Circuit breaker design |
Custom Setting schema and state-transition logic |
| Cross-channel notification design |
Error event → notification channel mapping |
Related Skills
integration/retry-and-backoff-patterns — HTTP retry backoff for external API calls
integration/api-error-handling-design — HTTP error response contracts
integration/event-driven-architecture-patterns — Platform Event architecture
admin/integration-pattern-selection — upstream pattern selection
1---2name: error-handling-in-integrations3description: "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. Trigger keywords: integration error handling, Platform Event retry, integration dead letter queue, EventBus RetryableException, integration circuit breaker, event bus trigger suspended. NOT for Apex exception handling (use apex-exception-handling skill), HTTP error response contracts (use api-error-handling-design), or retry backoff patterns (use retry-and-backoff-patterns)."4category: integration5salesforce-version: "Spring '25+"6well-architected-pillars:7 - Reliability8 - Operational Excellence9triggers:10 - "Platform Event trigger has been suspended after too many errors — how to recover and replay missed events"11 - "integration errors are not visible to operations team — need cross-channel error notification design"12 - "need to design a dead-letter queue pattern for failed integration messages in Salesforce"13 - "external system is unstable and integration needs a circuit breaker to stop flooding it"14 - "integration failures are silent and data is drifting between systems without anyone noticing"15tags:16 - integration17 - error-handling18 - platform-events19 - reliability20 - error-handling-in-integrations21inputs:22 - "Integration pattern in use (Platform Events, REST API callouts, CDC, Bulk API)"23 - "Current error visibility: how are failures currently surfaced"24 - "Recovery requirements: must failed messages be replayed or can they be discarded"25 - "External system stability characteristics"26outputs:27 - "Dead-letter queue pattern implementation guidance"28 - "Platform Event trigger suspension recovery procedure"29 - "Circuit breaker design for unstable external systems"30 - "Cross-channel notification pattern (Slack, email, Case creation)"31dependencies: []32version: 1.0.033author: Pranav Nagrecha34updated: 2026-04-1435metadata:36 source: https://skillmd.com/skills/banibratachatterjee/error-handling-in-integrations37---3839# Error Handling in Integrations4041This 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.4243---4445## Before Starting4647Gather this context before working on anything in this domain:4849- Platform Events retain messages for 72 hours (replay window). The stable deduplication key is the event message ID — not the Replay ID, which can be corrupted after Salesforce maintenance events.50- `EventBus.RetryableException` triggers up to 9 automatic retries before the Platform Event trigger is suspended. A suspended trigger stops processing ALL new events on that channel.51- Existing skills cover related but distinct topics: `integration/retry-and-backoff-patterns` covers HTTP retry backoff; `integration/api-error-handling-design` covers HTTP error response contracts. This skill covers orchestration-layer routing and recovery.52- The most critical mistake: throwing RetryableException for permanent errors (bad data, invalid config) causes 9 retries of a record that will never succeed, then suspends the trigger — blocking all event processing.5354---5556## Core Concepts5758### Platform Event Trigger Suspension and Recovery5960Failure escalation path:611. EventBus.RetryableException thrown → up to 9 automatic retries622. After 9 failures: trigger suspended — all new events stop processing633. Re-enable: Setup > Platform Events > [Event] > Subscribe Triggers > Resume644. Set Replay ID on re-enable to replay missed events from the 72-hour window6566Recovery 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.6768### Dead-Letter Queue Pattern6970Salesforce has no built-in DLQ. Implement explicitly:71- Custom object `Integration_DLQ__c` with: Source_System__c, Event_Type__c, Payload__c (JSON text), Error_Message__c, Retry_Count__c, Status__c (Pending / Failed_Max_Retries / Resolved)72- Scheduled Apex retries Pending DLQ entries periodically73- After max retries: mark as Failed_Max_Retries and trigger ops notification7475### Circuit Breaker7677For unstable external systems:78- Track consecutive failures in a Custom Setting (failure count + timestamp)79- CLOSED (normal): calls go through80- OPEN (threshold exceeded): skip external call, log OPEN state, notify ops81- HALF_OPEN (after cooldown): attempt one test call; success → CLOSE; failure → OPEN again8283### Cross-Channel Notification8485- Platform Event `Integration_Error__e` → Flow → Email Alert for standard failures86- Platform Event → Named Credential callout to Slack webhook for high-severity87- Case creation for SLA-impacting failures requiring human resolution88- CRM Analytics or Lightning report on DLQ volume for operations dashboards8990---9192## Common Patterns9394### Pattern: RetryableException for Transient, DLQ for Permanent9596```apex97trigger OrderEventTrigger on OrderEvent__e (after insert) {98 for (OrderEvent__e event : Trigger.new) {99 try {100 OrderIntegrationService.processEvent(event);101 // Store Replay ID on success102 Integration_State__c.getInstance().Last_Replay_Id__c = event.ReplayId;103 update Integration_State__c.getInstance();104 } catch (OrderIntegrationService.TransientException e) {105 // Transient: throw RetryableException for auto-retry106 throw new EventBus.RetryableException('Transient: ' + e.getMessage());107 } catch (Exception e) {108 // Permanent: write to DLQ, do NOT throw RetryableException109 insert new Integration_DLQ__c(110 Event_Type__c = 'OrderEvent',111 Payload__c = JSON.serialize(event),112 Error_Message__c = e.getMessage(),113 Status__c = 'Pending_Retry'114 );115 }116 }117}118```119120---121122## Decision Guidance123124| Failure Scenario | Recommended Pattern | Reason |125|---|---|---|126| Transient external error (timeout, 503) | RetryableException | Platform auto-retry handles transient failures |127| Permanent data error (invalid payload) | Write to DLQ; no RetryableException | RetryableException on permanent errors suspends trigger |128| External system down > 1 hour | Circuit breaker OPEN + DLQ accumulate | Prevent cascade failures and API limit exhaustion |129| Trigger suspended | Recovery runbook: Replay ID re-enable | 72-hour window enables recovery |130| Silent failures not visible to ops | Cross-channel notification platform event | Ops must know about failures immediately |131132---133134## Recommended Workflow1351361. Identify the integration pattern (Platform Events, REST, CDC, Bulk API) — each has different failure modes.1372. For Platform Event subscribers: implement RetryableException for transient errors only; DLQ for permanent failures.1383. Implement Replay ID tracking: store last successful Replay ID in a Custom Setting on every successful event.1394. Design DLQ object schema and Scheduled Apex retry job with configurable max retry count.1405. Design cross-channel notification: Platform Event for failures → Flow Email + Slack + Case creation based on severity.1416. For unstable external systems: implement circuit breaker using Custom Setting for failure count and circuit state.1427. Document the trigger suspension recovery runbook in team operations documentation.143144---145146## Review Checklist147148- [ ] RetryableException used only for transient errors (not permanent)149- [ ] DLQ pattern implemented for permanent failures150- [ ] Replay ID tracking implemented on every successful Platform Event151- [ ] Trigger suspension recovery runbook documented152- [ ] Cross-channel error notification designed153- [ ] Circuit breaker designed for unstable external systems154- [ ] DLQ retry job with max retry limit and ops alert threshold155156---157158## Salesforce-Specific Gotchas159160Non-obvious platform behaviors that cause real production problems:1611621. **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.1632. **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.1643. **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.165166---167168## Output Artifacts169170| Artifact | Description |171|---|---|172| DLQ schema and retry job | Integration_DLQ__c design and Scheduled Apex pattern |173| Trigger suspension recovery runbook | Steps to re-enable and replay after trigger suspension |174| Circuit breaker design | Custom Setting schema and state-transition logic |175| Cross-channel notification design | Error event → notification channel mapping |176177---178179## Related Skills180181- `integration/retry-and-backoff-patterns` — HTTP retry backoff for external API calls182- `integration/api-error-handling-design` — HTTP error response contracts183- `integration/event-driven-architecture-patterns` — Platform Event architecture184- `admin/integration-pattern-selection` — upstream pattern selection