Salesforce API Connection Testing: A Practical Troubleshooting Guide

A successful Salesforce login proves only that authentication worked. A usable API connection also needs to reach the correct org, use a valid instance URL, access the required objects, and perform the operations your integration depends on. The safest way to test a connection is to move from a harmless authenticated request to resource-level access, then test write operations only when the integration actually needs them.

What You Need Before Testing the Connection

Start with the Salesforce org you intend to test, an API user with the required access, and an OAuth configuration for authentication. Salesforce uses OAuth access tokens to authorise API requests, with current documentation directing new integrations toward External Client Apps for OAuth configuration.

You should also know which Salesforce API your integration uses and which objects or resources it needs. A connection that reaches one endpoint may still fail when it tries to access an object the authenticated user cannot use.

Use a supported Salesforce API version throughout the test. Salesforce currently supports Platform API versions 31.0 through 67.0; REST requests made against retired versions return 410 GONE.

Step 1: Authenticate and Capture the Instance URL

OAuth authentication returns an access token to send with subsequent Salesforce API requests. In Postman, the token details also show the instance_url associated with the org you authenticated against.

Salesforce's Trailhead instructions tell users to copy this value and use it as the endpoint for later requests, since it identifies the environment your requests should reach. Reusing a hardcoded endpoint from another sandbox, Developer Edition org, or production environment can send the request to the wrong place.

At this stage, an authentication failure usually points to the OAuth configuration, credentials, login settings, or application access, not the business logic of the request itself.

Step 2: Send a Low-Risk Connection Request

A read-only request gives you a cleaner first connection test than immediately creating or updating data:

GET /services/data/vXX.X/limits

Salesforce recommends the Limits resource as an easy way to test an authentication token, and its own Postman Trailhead exercise uses this same GET Limits call as its quick connection test, expecting a 200 OK response.

A successful response confirms the token is valid, the org is reachable, and the request can access the REST API. It does not confirm the integration has permission to use every object or operation it needs; that's the next step.

Step 3: Test the Salesforce Resources Your Integration Uses

Authentication alone doesn't prove an integration can reach Accounts, Contacts, Opportunities, custom objects, or other resources involved in its workflow. A useful next step is an object-level request such as:

GET /services/data/vXX.X/sobjects/Account/describe

The Describe resource returns metadata for the selected object, including its fields and relationships. Replace Account with the actual standard or custom object your integration uses, rather than relying only on tutorial examples.

From there, send a small SOQL query or retrieve a known test record to check whether the authenticated user can access the data the integration expects. Salesforce's Query resource supports SOQL requests against data available to the org and user.

Once basic object access is confirmed, broader CRUD scenarios, request validation, negative tests, and response assertions are covered in more depth in this Salesforce API testing guide.

Step 4: Test Write Access Only When You Need It

Create, update, and delete requests should come after basic connectivity and read access have worked. For an integration that writes Salesforce data, use a controlled record in a sandbox or other appropriate test environment:

• Create the record.
• Capture its returned ID.
• Retrieve it to inspect the saved values.
• Update it if the workflow requires that.
• Remove the test data afterward.

Salesforce's sObject REST resources support creating, retrieving, updating, and deleting individual records. Keeping these operations separate from the initial connection check makes troubleshooting easier, since you already know authentication and basic API access are working.

What Different API Failures Usually Mean

The HTTP response helps narrow down which part of the connection needs attention.

• 400 Bad Request: The request itself is invalid or contains data Salesforce cannot process. Inspect the endpoint, IDs, parameters, and request body.
• 401 Unauthorized: The OAuth token or session is invalid or expired. Obtain a valid token before retrying.
• 403 Forbidden: Salesforce received the request but refused access. User permissions or access to the requested resource may be the problem.
• 404 Not Found: The requested resource cannot be found or has been removed. Review the resource path, object name, record ID, and endpoint.
• 410 Gone: The requested REST resource or API version has been retired. Move the integration to a currently supported version.

The response body matters as much as the status code. Salesforce includes error information that can identify the affected resource or field, so avoid troubleshooting from the HTTP code alone.

Keep Sandbox and Production Connections Separate

Tokens, instance URLs, users, permissions, and data all belong to the Salesforce org where authentication occurred. A token obtained for a sandbox should stay with that sandbox configuration rather than being mixed into production requests.

Environment variables in Postman or your automation framework are a simple way to separate credentials, instance URLs, API versions, and test data between environments. Salesforce's own Postman guidance uses environment-specific login and instance URL values for this reason.

Conclusion

A useful Salesforce API connection test goes beyond one successful response. Authenticate first, send a harmless request such as GET Limits, test access to the actual Salesforce objects your integration needs, and add write operations only when the workflow requires them. This sequence makes failures easier to isolate before the integration moves into broader functional or regression testing.