Return webhook errors in an endpoint response

The External Tax Calculation webhook and Shipping Calculator webhook can be invoked by order-handling endpoints in the Store and Agent APIs. When one of these webhooks returns an error, the error is passed to the endpoint that called the webhook so it can be included in the endpoint's response.

The description and errorCode properties for each error in the webhook response are returned to the specific endpoint that invoked the webhook. This information is then included in the errors property in the endpoint response to make it available to the storefront or Agent Console.

The information returned by the endpoint varies depending on the type of error returned by the webhook. There are three main situations where errors may be returned:

• The webhook response is valid, but the response body includes errors.
• The webhook response is invalid. Depending on why the response is invalid, it may or may not include errors.
• The webhook does not return a response. This is typically due to network issues.

If the webhook response is valid, but the response body includes errors, the webhook returns a status code of 200. The endpoint then returns a status code of 400, and the errors property in the endpoint response includes the errors present in the webhook response body. For example:

{
  "errorCode": "40001"
  "message": "Please check the shipping address and try again.",
  "errors": [
    {
      "errorCode": "12345",
      "message": "First error in response"
    },
    {
      "errorCode": "67890",
      "message": "Second error in response"
    }
  ],
  "status": "400"
}

If the webhook response is invalid, the webhook returns a 400 or 500 level status code. The status code returned by the endpoint is the same as the webhook response status code. The errors property in the endpoint response includes an error message indicating the webhook response is invalid, as well as the errors present in the webhook response body. For example:

{
  "errorCode": "28088",
  "message": "Please check the selected shipping method. The previously selected shipping method is no longer available.",
  "errors": [

    {
      "errorCode": "402",
      "message": "Invalid response code of 402 received for webhook calculateShipping"
    },
    {
      "errorCode": "11111",
      "message": "First error in response"
    },
    {
      "errorCode": "22222",
      "message": "Second error in response"
    }
  ],
  "status": "402"
}

If there is no webhook response, the endpoint response status code is 502. The errors property in the endpoint response includes an error message with the actual exception.

Notes about the Shipping Calculator webhook

The error-handling behavior described above applies to the Shipping Calculator webhook when either an invalid shipping method or a valid external shipping method is used. If a valid internal shipping method is selected, however, no error is produced even if the webhook fails, returns an invalid response, or returns a valid response with errors.

In addition to the order endpoints, the Store and Agent shipping method endpoints can invoke the Shipping Calculator webhook, but only to retrieve the list of external shipping methods. If any errors are present in the webhook response body, the external shipping methods are not included in the endpoint response, but the endpoint does not return an error.