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
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.
Error Status Codes
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.
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.
1{2 "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/request-timeout",3 "title": "Request Timeout",4 "detail": "The request could not be processed by the system within the timeout threshold."5}
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.
Note
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:
1{2 "title": "You do not have enough credit",3 "type": "https://api.commercecloud.salesforce.com/documentation/error/v1/errors/not-enough-money",4 "detail": "Your current balance is 30, but that costs 50",5 "instance": "/account/12345/msgs/abc"6}
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:
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.
j