Salesforce REST API: 5 Things to Check When an Integration Fails

Connecting Salesforce with an external application is common in modern CRM development. An integration might exchange customer details, sync orders, or send updates between systems.

But when an API integration fails, the cause is not always obvious. The request may look correct while authentication, permissions, or data validation creates the actual problem.

Here are five things Salesforce developers should check when troubleshooting REST API integrations.

1. Verify Authentication

Start by checking whether the integration is authenticated correctly.

Review the OAuth configuration, access token, connected app or external client configuration, and the permissions assigned to the integration user.

For Salesforce callouts, use Named Credentials and External Credentials where appropriate instead of manually managing authentication details in Apex.

Never place passwords, access tokens, or client secrets directly in source code.

1. Check the API Endpoint

Confirm that the request uses the correct Salesforce instance URL and API endpoint.

For example, a REST API request to retrieve an Account record follows this general pattern:

GET /services/data/vXX.X/sobjects/Account/{recordId}
Authorization: Bearer

Replace vXX.X with a supported API version and {recordId} with the actual record ID.

A wrong endpoint, unsupported API version, or incorrect record ID can cause the request to fail.

1. Inspect the HTTP Status Code

The HTTP status code helps narrow down the problem.

Common examples include:

400 Bad Request: The request may contain invalid data or parameters.

401 Unauthorized: Authentication may be missing or invalid.

403 Forbidden: The authenticated user may lack the required access.

404 Not Found: The requested resource may not exist at that endpoint.

5xx errors: The server or a related service may have encountered an error.

These are general troubleshooting clues, not absolute diagnoses. Always inspect the response body for additional details.

1. Review Permissions and Data Access

Successful authentication does not automatically grant access to every Salesforce record or field.

Check the integration user's object permissions, field-level security, and record access.

For example, an integration user might be able to read Accounts but lack permission to access a particular custom field.

Testing with an administrator account alone can hide permission problems that will affect the actual integration user.

1. Log Errors Without Exposing Sensitive Data

Useful logs help developers identify recurring failures and understand what happened during a request.

Capture relevant information such as:

Request operation

HTTP status code

Timestamp

Error category

A correlation or transaction identifier

Avoid logging access tokens, passwords, or unnecessary personal information. Also consider retry handling for temporary failures, using suitable limits and backoff to prevent repeated requests from overwhelming the service.

Final Thoughts

Reliable Salesforce REST API integrations depend on more than a successful request. Authentication, endpoints, permissions, error handling, and logging all need attention.

When troubleshooting, change one variable at a time and test with the same user and environment used by the real integration. This makes the root cause easier to identify.