Salesforce API Testing: Check Connections and Find Failures

Updated 5 November 2026 · Standard formula, shown below

To test a Salesforce API connection, send a small authenticated request to a Salesforce endpoint and confirm both the HTTP response and the returned data. If it fails, inspect the response code and body, then check the credentials, token, permissions, endpoint, and request format in that order; the exact error usually points to the failing layer.

What a connection test actually checks

A successful connection is more than proof that a server can be reached. An API call must get through several independent checks: network access, authentication, authorization, endpoint routing, and request validation. A request can reach Salesforce but still fail because its token is expired, the connected app is not approved, or the user lacks access to the requested object.

Test the same API and authentication flow your integration uses. Salesforce integrations commonly use REST or SOAP APIs, and OAuth is widely used for authentication. A simple REST request to an appropriate endpoint, such as the identity URL returned during OAuth authorization or a query endpoint, can verify that a token works. Use an operation that is safe and small; a read-only request is preferable for an initial check.

Run a minimal API test

Use the integration’s existing approved credentials and the correct Salesforce instance URL. For a REST request, provide the access token as a bearer token in the Authorization header. For example, the general shape of a query request is:

GET https://your-instance.my.salesforce.com/services/data/vXX.X/query?q=SELECT+Id+FROM+Account+LIMIT+1
Authorization: Bearer YOUR_ACCESS_TOKEN

Replace the host with the instance URL issued for the session and use an API version supported by your org. Do not paste real access tokens into shared logs, tickets, or public tools. A command-line client, API client, or the application’s own diagnostic feature can send the same request; avoid changing several variables at once, or it becomes harder to identify the cause.

Confirm the integration is using the intended Salesforce org, user, and environment, such as production or a sandbox.
Check that the token is present and has not expired. If needed, obtain a fresh token through the configured OAuth flow rather than reusing an old one.
Send a low-impact request to a known endpoint using the correct instance host and API version.
Record the HTTP status, response body, request time, and any Salesforce request or error identifier. Remove secrets before sharing diagnostic output.
If the basic request succeeds, test the specific object, fields, and operation the integration needs.

Read the response to locate the failure

The HTTP status is a useful first clue, but it is not a complete diagnosis. Read the response body as well: Salesforce error responses often include a code and message that narrow the cause. Also inspect the client’s own logs for the full request URL, headers with secrets redacted, and whether it received a response at all.

No response, timeout, or DNS error: investigate the client’s network route, DNS resolution, proxy, firewall, TLS configuration, and whether the configured host is reachable. These problems occur before Salesforce can return an API error.
401 Unauthorized: verify the access token, authorization header, token expiry, and instance URL. A token issued for one org or host should not be assumed to work with another. Re-authenticate using the configured OAuth flow.
403 Forbidden: the request may be authenticated but not permitted. Check the user’s API access, profile or permission sets, connected-app access, and object- and field-level permissions. The precise message matters.
404 Not Found: check the URL path, API version, object or resource name, and whether the request is being sent to the instance associated with the session. An incorrect path can look like a connection problem even when authentication works.
400 Bad Request: inspect the query, JSON or XML body, required fields, data types, URL encoding, and content-type header. A malformed request can fail after the connection and authentication are already successful.
429 or a limit-related response: check the response details and org usage. API limits and temporary service conditions differ from credential failures; reduce unnecessary calls and follow Salesforce’s response guidance.

These are diagnostic patterns, not guarantees: status codes can depend on the endpoint and the exact request. When the message is unclear, reproduce the call with the smallest possible request and compare it with a known-good call from the same environment.

Trace the failure through the integration

If a request works in an API client but fails in the application, the API may be reachable while the application’s configuration or request construction is wrong. Compare the two calls carefully, including host, path, method, API version, authorization scheme, headers, query parameters, and body. Check whether the application is refreshing tokens and updating its instance URL after authentication.

For a failure that occurs only sometimes, note the time, frequency, affected operation, and whether retries change the outcome. Look for token refresh races, transient network interruptions, rate limiting, or a batch containing one invalid record. If Salesforce returns an identifier for the failed request, include it when consulting the organization’s Salesforce administrator or support channel. Do not repeatedly retry a write request without understanding whether the first attempt succeeded; that can create duplicate records or other side effects.

Check permissions and request details

Authentication identifies the user or integration, while authorization determines what that identity may do. A token can be valid even when a query fails because the user cannot access the object, a field is hidden, or the connected app’s policies prevent access. Test with the intended integration user and grant only the permissions needed for the operation.

For queries and writes, verify that the request matches the API’s expected format. Check field API names rather than display labels, confirm required fields are supplied, and ensure JSON values have the expected types. A successful simple query proves that some API access works; it does not prove that every object, field, or write operation is available.

Common misconceptions and safe troubleshooting

“The server responded, so the connection is fine” is only partly true: it confirms some network path, not that the API call is authorized or valid. Likewise, a successful login does not prove that a specific API operation is allowed. Separate the test into layers and change one setting at a time.

Do not put access tokens, client secrets, or passwords in source control, screenshots, or unredacted logs.
Use a sandbox for tests that might create, update, or delete records. Prefer read-only requests when checking connectivity.
Keep the instance URL returned by the authentication flow where the integration can use it; avoid assuming a fixed host applies to every org or session.
Use retries cautiously. Retry only errors that are plausibly transient, and make write operations safe against duplicate execution where possible.

Frequently Asked Questions

How do I know whether Salesforce is reachable or authentication is failing?
Look for whether the client receives an HTTP response. A timeout or DNS error points toward network or endpoint reachability; an HTTP authentication error means a server responded, so inspect the token, host, and OAuth configuration.

What is the simplest Salesforce API connection test?
Send a small, read-only REST request with a valid access token to the correct instance URL, such as an identity or basic query endpoint. Check both the status and response body.

Why does my API client work but my integration fail?
The application may use a different org, host, token, API version, header, or request body. Compare the actual requests, redacting credentials, and check how the application refreshes its token.

Does a 401 always mean the password is wrong?
No. It commonly points to a missing, expired, invalid, or incorrectly applied access token, or a mismatch between the token and instance URL. Salesforce API authentication often uses OAuth rather than sending a user password with each request.

How can I test without changing Salesforce data?
Use a read-only identity or query request with minimal scope. For any operation that may write data, use a sandbox and avoid repeating the request until you know whether the earlier attempt completed.

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.