Integration Error Handling Checklist
A working checklist for designing and reviewing how Salesforce integrations fail, retry, log and recover, with examples of error classification and partial-success handling.
Integrations rarely fail loudly. A token expires, a validation rule is added, a record is locked for a few seconds, and records stop arriving without anyone noticing until a customer complains. Good error handling is designed before go-live, not added after the first incident.
Use this checklist when designing a new integration with Salesforce, or when reviewing one that already runs. It applies whether the integration is point-to-point, runs through middleware, or uses platform events.
The checklist
- Every error is classified as transient (worth retrying) or permanent (needs a person or a code fix).
- Retries use backoff with jitter and a maximum number of attempts, so a struggling system is not hammered.
- Writes are idempotent. Use upsert on an External ID, or an idempotency key, so a retried request cannot create duplicates.
- Partial success is handled. Batch and composite calls can succeed for some records and fail for others; each record's result is checked.
- Failures are logged with context: source system, record identifier, payload reference, error code, message and timestamp, without logging secrets or unnecessary personal data.
- Failed messages are kept for replay, in a dead-letter queue or error table, with a tested way to resubmit them.
- Someone is alerted when error rates or queue depth cross a threshold, and the alert says where to look.
- API usage is monitored against your org's limits. Check current limits for your org in Salesforce Help or the System Overview page.
- Authentication failures are handled by refreshing tokens once, then alerting, rather than retrying indefinitely.
- There is a runbook that tells support staff how to diagnose, fix and replay each common failure.
Classifying common Salesforce errors
| Typical cause | Retry? | Action | |
|---|---|---|---|
| INVALID_SESSION_ID or HTTP 401 | Expired or revoked token | Once, after refresh | Refresh the token, then alert if it fails again |
| REQUEST_LIMIT_EXCEEDED | API allocation used up | Later, with backoff | Pause, alert and review call volume |
| UNABLE_TO_LOCK_ROW | Another process holds the record | Yes, with backoff | Retry a few times, then investigate data skew |
| HTTP 5xx or timeout | Temporary service or network issue | Yes, if the write is idempotent | Retry with backoff and check for duplicates |
| REQUIRED_FIELD_MISSING | Payload lacks a mandatory value | No | Route to the data owner and fix the source |
| FIELD_CUSTOM_VALIDATION_EXCEPTION | A validation rule rejected the data | No | Route to the data owner or review the rule |
| DUPLICATE_VALUE | A unique field already holds the value | No | Check the External ID and matching logic |
Reading a REST API error
The Salesforce REST API returns errors as a JSON array. The errorCode is what your classification logic should branch on; the message is for humans and may change wording.
[
{
"message": "Required fields are missing: [LastName]",
"errorCode": "REQUIRED_FIELD_MISSING",
"fields": ["LastName"]
}
]Handling partial success in Apex
When Apex receives a batch of records from an inbound integration, using allOrNone = false lets valid records save while failed ones are captured. This sample assumes an Account.External_Id__c External ID field and a custom Integration_Error__c object with text fields for the identifier, status code and message. It is a pattern to adapt, not production code.
public static void upsertAccounts(List<Account> records) {
Database.UpsertResult[] results =
Database.upsert(records, Account.External_Id__c, false);
List<Integration_Error__c> errors = new List<Integration_Error__c>();
for (Integer i = 0; i < results.size(); i++) {
if (results[i].isSuccess()) {
continue;
}
for (Database.Error err : results[i].getErrors()) {
errors.add(new Integration_Error__c(
Record_Key__c = records[i].External_Id__c,
Status_Code__c = String.valueOf(err.getStatusCode()),
Message__c = err.getMessage().left(255)
));
}
}
if (!errors.isEmpty()) {
insert errors;
}
}Related reading
- Salesforce API integration error handling goes deeper on retry design and logging.
- Platform events for decoupled integrations covers event-driven patterns and replay.
- Integration middleware vs point-to-point APIs helps decide where error handling should live.
- Securing Salesforce API integrations covers credentials, scopes and integration users.
Worried about silent integration failures?
GeekMidst can review your existing integrations against this checklist, or design error handling and monitoring into a new one from the start.
