Salesforce Platform: API Error Troubleshooting Guide

API (Application Programming Interface):

A set of protocols, tools, and definitions that allows external systems or applications to programmatically interact with Salesforce. APIs enable operations such as retrieving, creating, updating, or deleting data, as well as integrating Salesforce with other platforms and services.

1. Check error messages and status codes.

These are important pieces of information for troubleshooting. Here, we will cover some representative types of APIs.

When an error occurs with the REST API

Whether an error occurs or the response is normal, the response header includes an HTTP code, and the response body usually contains status codes and error responses information.

When an error occurs with the SOAP API

For errors due to improperly created messages, failed authentication, or similar issues, the API returns a SOAP error message using the relevant ExceptionCode.

When an error occurs with the Bulk API / Bulk API 2.0

During the execution of processes with the Bulk API, errors may be returned. Check the error codes and the Bulk API actions that are likely causing them.

2. Check if the API requests are within the limits and allocations.

The following limits and allocations apply to Salesforce Platform SOAP and REST APIs and any other API built on those frameworks, unless noted otherwise.

API Request Limits and Allocations

To better monitor your org’s API usage and limits, you can use these resources:

• The API Usage section of the System Overview page in Setup.

• The API Requests, Last 24 Hours item in the Organization Detail section of the System Overview page in Setup.

• The API Request Limit per Month usage-based entitlement, which shows you your org’s API calls aggregated over 30 days. This information can be found on the Company Information page in Setup.

• Information returned in the Sforce-Limit-Info response header for REST APIs.

• Information returned in the response body (in <type>API REQUESTS</type>) for SOAP APIs.

• The /limits call in the Lightning Platform REST API.

For the Bulk API, consider the following limits and allocations:

Bulk API and Bulk API 2.0 Limits and Allocations

For other Salesforce APIs like the Connect REST API, refer to the documentation for each API.

3.Consider implementing automatic retries for temporary errors.

API requests may respond with temporary errors. These can be caused by temporary high load on the API service or network path issues, among other factors. In actual use, you may encounter temporary errors. Therefore, it is important to anticipate such temporary errors and consider implementing a retry mechanism. By implementing automatic retries, you can use the API service more stably.

If the problem is not resolved after checking all the above guidelines, contact support with the following information:

- Organization ID where the error occurred

- API execution user (username)

- API type (REST API, SOAP API, Bulk API, etc.)

- Request date and time (including time zone)

- Request URL, method

- Request body

- Response body

Additionally, if errors start occurring in requests that previously did not have errors, it may indicate an issue not dependent on the request content. In such cases, the following information is also acceptable:

- Organization ID where the error occurred

- API execution user (username)

- API type (REST API, SOAP API, etc.)

- Time period when the error was confirmed (including time zone)

- Approximate frequency of errors (e.g., 8 out of 10 requests in 3 minutes)

- Information about the client tool used (Dataloader, another Salesforce organization, custom Java client, etc.)

- Detailed processing content (e.g., SOAP API method name like query(), REST API endpoint URL, etc.)

- Any other information that can help understand the error details (response body, logs from the API client application, SOQL, etc.)