HTTP Status Codes and Errors
To help you handle errors and special cases, the B2C Commerce APIs (SCAPI) return HTTP status codes and error messages.
The following tables list HTTP status codes and typical use cases.
| HTTP Status Code | Use Cases |
|---|
| 200 (OK) | GET, PUT, or POST request successfully completed. |
| 201 (Created) | POST or PUT request successfully created a new resource or relationship resource. |
| 204 (No Content) | Request successfully completed and returned no content. |
| 207 (Multi-Status) | Request succeeded with multiple status results for suboperations, for example: batch or partial responses. |
| HTTP Status Code | Use Cases |
|---|
| 400 (Bad Request) | Request contains invalid information, such as malformed parameters, malformed header values, or a malformed body. |
| 401 (Unauthorized) | Request is not authorized to be processed. |
| 403 (Forbidden) | Request is declined by the server. |
| 404 (Not Found) | Requested resource does not exist. |
| 405 (Method Not Allowed) | Resource does not support supplied HTTP method. |
| 409 (Conflict) | The request could not be completed due to a conflict with the current state of the resource. |
| 412 (Precondition Failed) | PATCH request provided an outdated last-known base point, which means the resource was changed on server, possibly by a concurrent request. |
| 415 (Unsupported Media Type) | Media type specified in "format" request parameter (or Accept header) is not supported. |
| 500 (Internal Server Error) | Request cannot be fulfilled because of an unexpected condition on the server. |
All B2C Commerce APIs share some common error messages, which can be returned by any API.
Documentation on the API level focuses on API-specific error messages.
| Type | Detail |
|---|
| missing-query-parameter | Missing required query parameter(s): '{missingParams}' |
| undefined-query-parameter | Query parameter '{undefinedParam}' is not defined in the API. |
| value-constraint-violation | Value for parameter '{parameterName}' violates API constraint '{constraintName}'. |
| constraint-violation | '{parameterName}' value constraint violated. Expected value is between '(x..y)'. |
| adhoc-logging-not-supported | This API does not support sdfc-log-level or sfdc-verbose headers. Remove these. |
| incorrect-preflight | A preflight request was malformed or incomplete: {detail} |
| Type | Detail |
|---|
| unauthorized | Unauthorized request |
| Type | Detail |
|---|
| forbidden | Access to requested resource is forbidden. |
| Type | Detail |
|---|
| resource-not-found | Could not find requested resource. |
| organization-not-found | No organization found for organizationId '{organizationId}'. |
| Type | Detail | Additional Information |
|---|
| method-not-allowed | The request method is not allowed for the requested resource. | |
| custom-apis-options | The OPTIONS method is not supported for custom APIs. | Troubleshooting Custom APIs |
| Type | Detail |
|---|
| request-uri-too-long | Request URL length limit has been exceeded. |
| Type | Detail |
|---|
| missing-content-type | The Content-Type header is missing. Expected: '{expected}' |
| unsupported-content-type | The media type in Content-Type header isn't supported. Expected: '{expected}' |
| unsupported-content-type | The charset in Content-Type header isn't supported. Expected: '{expected}' |
| Type | Detail |
|---|
| too-many-requests | You have performed too many requests with ad hoc logging in a short period of time. |
| Type | Detail |
|---|
| internal-server-error | Internal Server Error |
| Type | Detail | Additional Information |
|---|
| service-unavailable | The request could not be processed at this time. | |
| service-unavailable | The request has been throttled due to high resource consumption on server side. See 'sfdc_load' headers for details. | |
| system-under-maintenance | The request could not be processed as the system is currently under maintenance. | Maintenance Response Codes |
| site-under-maintenance | The request could not be processed as the site is currently under maintenance. | Maintenance Response Codes |
If responding to a SCAPI request takes too long, a HTTP 504 status code is returned:
| Type | Detail | Additional Information |
|---|
| request-timeout | The request could not be processed by the system within the timeout threshold. | Troubleshoot Request Timeouts |
Shopper APIs and Custom APIs must respond within 10 seconds, and SCAPI Admin API requests must respond within 60 seconds. If a response to a SCAPI request exceeds the timeout threshold, the HTTP 504 status code is returned.
If you are encountering issues with timeouts, seek to optimize your hook implementations.
Some API families, such as SLAS and Omnichannel Inventory (OCI), do not have gateway timeouts.
For status codes greater than or equal to 400, the API returns an error response following the RFC 7807 Problem Details format, for example:
The error response contains the following properties:
title: A short, human-readable summary of the problem type. It won't change from occurrence to occurrence of the problem, except for purposes of localization.type: A URI reference that identifies the problem type. When dereferenced, it should provide human-readable documentation for the problem type. When this member is not present, its value is assumed to be "about".detail: A human-readable explanation specific to this occurrence of the problem.instance: A URI reference that identifies the specific occurrence of the problem. It might or might not yield further information if dereferenced.
When handling SCAPI errors in your application:
- Always code to the HTTP response status code, not the HTTP response message.
- Use the last segment of the
type field to programmatically handle different error scenarios.
- Consider implementing retry logic for 503 errors, as these are typically temporary server issues.
- Validate input on the client side to minimize 400 errors.
- In case of 500 errors with an unknown root cause:
- Check for customization header (
sfdc_customization_error). If the value is "1", an error occurred within a hook execution.
- Copy the
sfdc_correlation_id response header value to trace down a root cause or open a support case.