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.

Success Status Codes

Error Status Codes

Common SCAPI Error Messages by HTTP Status Code

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.

400 (Bad Request)

401 (Unauthorized)

403 (Forbidden)

404 (Not Found)

405 (Method Not Allowed)

413 (Payload Too Large)

414 (Payload Too Large)

415 (Unsupported Media Type)

429 (Too Many Requests)

500 (Internal Server Error)

503 (Service Unavailable)

504 (Request Timeout)

If responding to a SCAPI request takes too long, a HTTP 504 status code is returned:

{
  "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/request-timeout",
  "title": "Request Timeout",
  "detail": "The request could not be processed by the system within the timeout threshold."
}

By default, Shopper API requests must respond within 10 seconds, and Custom API and SCAPI Admin API requests within 60 seconds. These timeouts are configurable via the Timeouts API. 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.

note: Some API families, such as SLAS and Omnichannel Inventory (OCI), do not have gateway timeouts.

Error Response Format

For status codes greater than or equal to 400, the API returns an error response following the RFC 7807 Problem Details format, for example:

{
  "title": "You do not have enough credit",
  "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/not-enough-money",
  "detail": "Your current balance is 30, but that costs 50",
  "instance": "/account/12345/msgs/abc"
}

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:blank".
• 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.

Best Practices for Error Handling

When handling SCAPI errors in your application:

1. Always code to the HTTP response status code, not the HTTP response message.
2. Use the last segment of the type field to programmatically handle different error scenarios.
3. Consider implementing retry logic for 503 errors, as these are typically temporary server issues.
4. Validate input on the client side to minimize 400 errors.
5. 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.