All APIs are mandated to use the default error-handling flow, which sanitizes error messages before sending them to the customer. APIs that cannot use this flow require an approved exception. The standard shared flow is configured in the PreFlow, invoking the FC-ErrorHandling policy. This framework can also be customized to append backend target errors directly to the response payload.
All error responses from the POST /v2/orders endpoint follow a consistent JSON structure to ensure predictable error handling. The HTTP status code in the response header indicates the general nature of the error.
The JSON body of an error response contains the following fields:
-
message (string): A human-readable description of the error. This often includes specific details about which validation rule failed.
-
errorType (string): A high-level classification of the error, such as validation, unauthorized, or internal.
-
code (number): The HTTP status code.
The following is an example of a validation error for an invalid fulfillment type:
{
"message": "failed to validate input: Fulfillment type must be one of SHIPPED, DIGITAL, STORE_PICK_UP, LOCAL_DELIVERY, STORE_DRIVE_UP, IN_PERSON, ",
"errorType": "validation",
"code": 400
}
The following tables contain a detailed breakdown of possible HTTP status codes and the specific errors associated with them.
This status code indicates a problem with the client's request, usually caused by malformed syntax or invalid data.
Validation errors (errorType: "validation")
These are the most common 400 errors and occur when the request body fails validation. Usually the base error message is "failed to validate input," followed by a more specific reason.