REST API Developer Guide
jNote: This release is in preview. Features described here don’t become generally available until the latest general availability date that Salesforce announces for this release. Before then, and where features are noted as beta, pilot, or developer preview, we can’t guarantee general availability within any particular time frame or at all. Make your purchase decisions only on the basis of generally available products and features.
Status Codes and Error Responses
Either when an error occurs or when a response is successful, the response header contains an HTTP code, and the response body usually contains:
- The HTTP response code
- The message accompanying the HTTP response code
- The field or object where the error occurred (if the response returns information about an error)
| HTTP response code | Description |
|---|---|
| 200 | “OK” success code, for GET, HEAD, and some PATCH requests. |
| 201 | “Created” success code, for POST requests and some PATCH requests. |
| 204 | “No Content” success code, for DELETE requests and some PATCH requests. |
| 300 | The value returned when an external ID exists in more than one record. The response body contains the list of matching records. |
| 304 | The request content hasn’t changed since a specified date and time. The date and time is provided in a If-Modified-Since header. See Get Object Metatdata Changes for an example. |
| 400 | The request couldn’t be understood, usually because the JSON or XML body contains an error. |
| 401 | The session ID or OAuth token used has expired or is invalid. The response body contains the message and errorCode. |
| 403 | The request has been refused. Verify that the logged-in user has appropriate permissions. If the error code is REQUEST_LIMIT_EXCEEDED, you’ve exceeded API request limits in your org. |
| 404 | The requested resource couldn’t be found. Check the URI for errors, and verify that there are no sharing issues. |
| 405 | The method specified in the Request-Line isn’t allowed for the resource specified in the URI. |
| 409 | The request couldn’t be completed due to a conflict with the current state of the resource. Check that the API version is compatible with the resource you’re requesting. |
| 410 | The requested resource has been retired or removed. Delete or update any references to the resource. |
| 412 | The request wasn’t executed because one or more of the preconditions that the client specified in the request headers wasn’t satisfied. For example, the request includes an If-Unmodified-Since header, but the data was modified after the specified date. |
| 414 | The length of the URI exceeds the 16,384-byte limit. |
| 415 | The entity in the request is in a format that’s not supported by the specified method. |
| 420 | Salesforce Edge doesn’t have routing information available for this request host. Contact Salesforce Customer Support. |
| 428 | The request wasn’t executed because it wasn’t conditional. Add one of the Conditional Request Headers, such as If-Match, to the request and resubmit it. |
| 431 | The combined length of the URI and headers exceeds the 16,384-byte limit. |
| 500 | An error has occurred within Lightning Platform, so the request couldn’t be completed. Contact Salesforce Customer Support. |
| 502 | Salesforce Edge wasn’t able to communicate successfully with the Salesforce instance. |
| 503 | The server is unavailable to handle the request. Typically this issue occurs if the server is down for maintenance or is overloaded. |
Incorrect ID example
Using a non-existent ID in a request using JSON or XML (request_body.json or request_body.xml)
1[
2{
3 "fields" : [ "Id" ],
4 "message" : "Account ID: id value of incorrect type: 001900K0001pPuOAAU",
5 "errorCode" : "MALFORMED_ID"
6}
7]Resource doesn’t exist
Requesting a resource that doesn’t exist, for example, you try to create a record using a misspelled object name
1[
2{
3 "message" : "The requested resource does not exist",
4 "errorCode" : "NOT_FOUND"
5}
6]For extended error codes, see Core Data Types Used in API Calls.