1. Find the first point of failure

Map the actual route: source application, connector or middleware, Salesforce, and any downstream service. Confirm which component makes the request and which component reports the error. An outbound Salesforce callout needs a different investigation from an external application writing into Salesforce.

Record the environment, endpoint, integration user, API version, correlation identifier, and last successful run. Compare a failed transaction with a successful one. Differences in record type, customer, payload size, or processing time often narrow the investigation quickly.

Read the response body alongside the HTTP status. Salesforce REST responses can include an error code and details about the affected request. A dashboard message such as “sync failed” loses the evidence needed to distinguish authentication from data or permission problems. [1]

Keep secrets and unnecessary customer information out of diagnostic logs. Capture enough context to reproduce the failure using appropriately protected test data.

Build a short change timeline around the first failure. Include connector releases, permission changes, Salesforce deployments, credential updates, and source-system changes. Confirm timestamps and timezones across logs. A problem that appears after a deployment deserves comparison with the previous configuration, even when the deployment was considered unrelated.

2. Separate authentication from authorization

Authentication establishes identity; authorization determines what that identity can do. First confirm that the token belongs to the intended org and that the configured endpoint matches the target environment. Check recent credential rotations, revoked access, and changes to the integration user.

Review the OAuth flow and app policies. For an external client app, confirm the configured scopes and, where applicable, callback URL and refresh-token settings. A connector must support the policies actually enabled for its app. [2]

Renew credentials using the configured flow. Do not assume every integration receives a refresh token: Salesforce’s client credentials flow obtains another access token through the client credentials exchange. Escalate persistent authentication failures instead of repeatedly attempting the same request. [3]

Once authentication works, verify API access, object permissions, field access, and record visibility for the integration user. Reproduce the request with that identity; a successful administrator test does not establish that the integration has equivalent access. Use a dedicated user and grant only the permissions required. [3]

Document certificate expiry and secret rotation dates, including the person responsible for renewal. Test planned rotations before production changes so routine maintenance does not become an unexpected outage.

3. Inspect the payload and business rules

If some records succeed and others fail, inspect the rejected records before changing the connection. Compare required fields, field lengths, data types, restricted picklist values, relationship references, and validation requirements. Use field API names in mappings rather than assuming that display labels are interchangeable.

Pay attention to transformations. A date converted in the wrong timezone, a blank value treated as a deliberate deletion, or a number formatted with unexpected separators can change the meaning of a request. Document how nulls, empty strings, defaults, and currencies should behave.

Check whether a recent Salesforce change introduced a requirement the source system cannot satisfy. For example, an illustrative billing integration might fail after a new validation rule requires a billing country that its export never included.

Resolve the mismatch with the business owner. Correct the source, mapping, or narrowly defined rule behavior, then test representative records. Disabling validation across the org can turn an obvious failure into less visible data quality problems.

Create a small collection of example payloads covering new records, updates, missing optional values, long text, and unusual characters. Include records that should be rejected. This gives both teams an agreed contract for future changes and helps distinguish a mapping defect from an intentional business restriction.

4. Check capacity and individual results

Inspect API consumption around the failure window using Salesforce’s usage information and the REST Limits resource where appropriate. Evaluate total org activity, because another connector or an unexpected polling loop can consume capacity your integration also needs. Avoid assuming that every org has the same allocation.

Salesforce documents REQUEST_LIMIT_EXCEEDED with HTTP 403 when API protection limits are enforced. A client that recognizes only 429 as a capacity problem can misclassify the response and retry incorrectly. Use the Salesforce error code as well as the HTTP status. [4]

Reduce unnecessary requests, avoid repeatedly downloading unchanged records, and choose batching or Bulk API when the workload supports it. Confirm the connector’s actual request behavior instead of assuming that one scheduled run equals one API call.

For batch operations, retrieve individual record results. Successful request submission or a completed batch does not establish that every record succeeded. Preserve failures for correction and controlled replay. [5]

Track progress at the record level. If a job partially succeeds, restarting the entire import may repeat completed work. Store the successful identifiers and unresolved failures separately, then resume from a durable checkpoint that accurately reflects what the destination accepted.

5. Investigate automation and record contention

A request can authenticate correctly and contain valid fields, then fail when Salesforce processes the update. Review relevant flows, Apex triggers, validation, and managed package logic. Look for errors introduced after deployments and reproduce the problem with realistic record relationships and volumes.

When several workers update the same records or related parents, investigate UNABLE_TO_LOCK_ROW. Salesforce’s guidance describes contention from concurrent updates, triggers, and related records. Increasing the number of workers can worsen this situation. [6]

Identify which records attract competing writes. Coordinate overlapping jobs, reduce concurrency where necessary, and group work around shared parents. Review automation that extends transaction duration. Confirm which processing controls your chosen API and connector actually provide before changing execution settings.

If a retry succeeds, still investigate the pattern. Repeated contention can increase delays and consume capacity even when the final record eventually appears correct.

Test the repair under realistic concurrency. A single successful manual update does not reproduce several scheduled jobs writing related records together during the busiest part of the day.

6. Verify endpoints and network behavior

Check DNS resolution, TLS certificates, firewall rules, proxy behavior, and destination availability from the actual integration runtime. A request working from a developer’s laptop does not prove that the production worker follows the same route or has the same network permissions.

Compare production and sandbox configuration after refreshes or deployments. Confirm target domains, environment-specific credentials, and API versions. Review relevant service status information, but correlate any reported incident with your timestamps and affected service before assigning it as the cause.

For Salesforce calling an external service, inspect the named credential, linked external credential, and principal access. Named credentials define the callout endpoint, while external credentials handle authentication and principal permissions. These settings are distinct from an external application authenticating into Salesforce. [7]

Measure where a timeout occurs before increasing it. A longer wait cannot correct an unreachable destination or a transaction that consistently exceeds the intended processing model.

7. Make retries safe and selective

A timeout means the caller did not receive confirmation; the receiving system may already have completed the operation. Replaying an unprotected create request can produce duplicate orders, cases, or other records.

Use a stable business identifier and a documented duplicate-handling strategy. Salesforce supports upsert through an external ID field, allowing a matching record to be updated or a missing record to be created. Plan uniqueness deliberately: multiple matching records produce an error. [9]

Record request identifiers and outcomes so the receiver can recognize repeated operations. An upsert can reduce duplicate record creation, but repeated updates may still trigger automation or downstream actions. Review those effects as part of idempotency: repeating a request should not repeat its business impact. [8]

Retry temporary failures with bounded attempts and increasing delays with jitter. Correct invalid data, configuration, and persistent access failures before replaying them. Put exhausted failures into a review queue with an owner, and preserve the original business identifier during recovery.

Set a maximum recovery window as well as an attempt limit. An old update may no longer be appropriate after a newer change has arrived. Compare business versions or timestamps according to the agreed conflict policy.

8. Use this first-check error guide

These signals guide the investigation. Confirm the full response and execution context before applying a fix.

9. Monitor business outcomes, not just uptime

A running connector can still leave records missing or outdated. Track delivery latency, oldest pending item, failed record count, retry volume, and the last confirmed successful transaction. Alert when the business deadline is at risk, not only when the process stops.

Reconcile source and destination records using stable identifiers and relevant business totals. Investigate missing, duplicated, and inconsistent records separately. Matching overall record counts does not prove that the same records, values, and statuses exist in both systems.

Agree which system owns each shared field and how conflicts are resolved. Otherwise, a delayed update can overwrite newer information, or two systems can repeatedly overwrite each other. Document expected synchronization delays so teams can distinguish normal waiting from a stalled process.

After fixing the immediate fault, replay a controlled sample, verify the results, and recover the remaining backlog in monitored groups. Assign a technical owner and a business contact to every integration.

Keep a short incident runbook beside the connector documentation. It should explain where to find errors, how to pause processing, who approves a replay, and how to verify completion. Record the affected business period and outstanding exceptions. An incident is not fully resolved while another team is still repairing unexplained discrepancies manually.

10. Close the incident with evidence

Use this checklist before declaring the integration healthy again.

Frequently asked questions