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. 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."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"15 - "integration error handling retry circuit breaker dead letter queue"16tags:17 - integration18 - error-handling19 - platform-events20 - reliability21 - error-handling-in-integrations22inputs:23 - "Integration pattern in use (Platform Events, REST API callouts, CDC, Bulk API)"24 - "Current error visibility: how are failures currently surfaced"25 - "Recovery requirements: must failed messages be replayed or can they be discarded"26 - "External system stability characteristics"27outputs:28 - "Dead-letter queue pattern implementation guidance"29 - "Platform Event trigger suspension recovery procedure"30 - "Circuit breaker design for unstable external systems"31 - "Cross-channel notification pattern (Slack, email, Case creation)"32dependencies: []33version: 1.0.034author: Pranav Nagrecha35updated: 2026-04-1436metadata:37 source: https://skillmd.com/skills/pranavnagrecha/error-handling-in-integrations38---3940# Error Handling in Integrations4142This 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.4344---4546## Before Starting4748Gather this context before working on anything in this domain:4950- 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.51- `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.52- 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.53- 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.5455---5657## Core Concepts5859### Platform Event Trigger Suspension and Recovery6061Failure escalation path:621. EventBus.RetryableException thrown → up to 9 automatic retries632. After 9 failures: trigger suspended — all new events stop processing643. Re-enable: Setup > Platform Events > [Event] > Subscribe Triggers > Resume654. Set Replay ID on re-enable to replay missed events from the 72-hour window6667Recovery 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.6869### Dead-Letter Queue Pattern7071Salesforce has no built-in DLQ. Implement explicitly:72- 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)73- Scheduled Apex retries Pending DLQ entries periodically74- After max retries: mark as Failed_Max_Retries and trigger ops notification7576### Circuit Breaker7778For unstable external systems:79- Track consecutive failures in a Custom Setting (failure count + timestamp)80- CLOSED (normal): calls go through81- OPEN (threshold exceeded): skip external call, log OPEN state, notify ops82- HALF_OPEN (after cooldown): attempt one test call; success → CLOSE; failure → OPEN again8384### Cross-Channel Notification8586- Platform Event `Integration_Error__e` → Flow → Email Alert for standard failures87- Platform Event → Named Credential callout to Slack webhook for high-severity88- Case creation for SLA-impacting failures requiring human resolution89- CRM Analytics or Lightning report on DLQ volume for operations dashboards9091---9293## Common Patterns9495### Pattern: RetryableException for Transient, DLQ for Permanent9697```apex98trigger OrderEventTrigger on OrderEvent__e (after insert) {99 for (OrderEvent__e event : Trigger.new) {100 try {101 OrderIntegrationService.processEvent(event);102 // Store Replay ID on success103 Integration_State__c.getInstance().Last_Replay_Id__c = event.ReplayId;104 update Integration_State__c.getInstance();105 } catch (OrderIntegrationService.TransientException e) {106 // Transient: throw RetryableException for auto-retry107 throw new EventBus.RetryableException('Transient: ' + e.getMessage());108 } catch (Exception e) {109 // Permanent: write to DLQ, do NOT throw RetryableException110 insert new Integration_DLQ__c(111 Event_Type__c = 'OrderEvent',112 Payload__c = JSON.serialize(event),113 Error_Message__c = e.getMessage(),114 Status__c = 'Pending_Retry'115 );116 }117 }118}119```120121---122123## Decision Guidance124125| Failure Scenario | Recommended Pattern | Reason |126|---|---|---|127| Transient external error (timeout, 503) | RetryableException | Platform auto-retry handles transient failures |128| Permanent data error (invalid payload) | Write to DLQ; no RetryableException | RetryableException on permanent errors suspends trigger |129| External system down > 1 hour | Circuit breaker OPEN + DLQ accumulate | Prevent cascade failures and API limit exhaustion |130| Trigger suspended | Recovery runbook: Replay ID re-enable | 72-hour window enables recovery |131| Silent failures not visible to ops | Cross-channel notification platform event | Ops must know about failures immediately |132133---134135## Recommended Workflow1361371. Identify the integration pattern (Platform Events, REST, CDC, Bulk API) — each has different failure modes.1382. For Platform Event subscribers: implement RetryableException for transient errors only; DLQ for permanent failures.1393. Implement Replay ID tracking: store last successful Replay ID in a Custom Setting on every successful event.1404. Design DLQ object schema and Scheduled Apex retry job with configurable max retry count.1415. Design cross-channel notification: Platform Event for failures → Flow Email + Slack + Case creation based on severity.1426. For unstable external systems: implement circuit breaker using Custom Setting for failure count and circuit state.1437. Document the trigger suspension recovery runbook in team operations documentation.144145---146147## Review Checklist148149- [ ] RetryableException used only for transient errors (not permanent)150- [ ] DLQ pattern implemented for permanent failures151- [ ] Replay ID tracking implemented on every successful Platform Event152- [ ] Trigger suspension recovery runbook documented153- [ ] Cross-channel error notification designed154- [ ] Circuit breaker designed for unstable external systems155- [ ] DLQ retry job with max retry limit and ops alert threshold156157---158159## Salesforce-Specific Gotchas160161Non-obvious platform behaviors that cause real production problems:1621631. **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.1642. **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.1653. **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.166167---168169## Output Artifacts170171| Artifact | Description |172|---|---|173| DLQ schema and retry job | Integration_DLQ__c design and Scheduled Apex pattern |174| Trigger suspension recovery runbook | Steps to re-enable and replay after trigger suspension |175| Circuit breaker design | Custom Setting schema and state-transition logic |176| Cross-channel notification design | Error event → notification channel mapping |177178---179180## Related Skills181182- `integration/retry-and-backoff-patterns` — HTTP retry backoff for external API calls183- `integration/api-error-handling-design` — HTTP error response contracts184- `integration/event-driven-architecture-patterns` — Platform Event architecture185- `admin/integration-pattern-selection` — upstream pattern selection