Sync error objects

Understand sync error objects.

When Commerce API detects a synchronous error, it returns an errors object in the response. This object will return the code, subcode, description, and message.

When the Commerce API encounters a synchronous error during an operation, it returns a detailed error object in the response. This error object provides developers precise information about what went wrong, allowing easier debugging and error handling. Below is the structure of an error object and examples of common errors.

Each error object contains the following fields:

  • code: A string identifier for the type of error encountered.

  • subcode: A more specific string identifier that provides additional detail about the error.

  • description: A field that can provide a human-readable explanation of the error, which could be null if not applicable.

  • message: A descriptive message that explains the nature of the error.


  "errors": [
      "code": "invalid-request",
      "subcode": "invalid-task-status",
      "description": null,
      "message": "The value(s):[ABC, DEF] of taskStatus is invalid, expected value(s) is:[COMPLETED, FAILED, PROCESSING, PUBLISHED]"
      "code": "invalid-request",
      "subcode": "startingAfter-and-endingBefore-cannot-be-both-provided",
      "description": null,
      "message": "[startingAfter] and [endingBefore] can not both be provided."

In the examples above, you can see how the Commerce API provides clear feedback on two types of synchronous errors: an invalid task status and the mutual exclusivity of startingAfter and endingBefore parameters. By analyzing these error objects, developers can quickly identify and correct issues in their API requests.

How to fix these errors


The error identified by the code invalid-request and subcode invalid-task-status indicates that the API does not recognize the task status value provided in the request. To resolve this error:

  1. Verify the task status value(s) you provided in your request.

  2. Ensure that your request only includes task status values the API recognizes: COMPLETED, FAILED, PROCESSING, or PUBLISHED.

  3. Update your request to include only the valid task status values and try again.


The error with the code invalid-request and subcode startingAfter-and-endingBefore-cannot-be-both-provided indicates you provided the startingAfter and endingBefore parameters in the request, which is not permitted. To fix this error:

  1. Review your API request to identify where you use the startingAfter and endingBefore parameters.

  2. Decide which parameter is most appropriate for your use case.

    • Use startingAfter to fetch records after a specific point in time.

    • Use endingBefore to fetch records before a particular point in time.

  3. Remove the unnecessary parameter from your request and submit it again.

By correcting these issues as suggested, you should be able to proceed without encountering these errors.

Last updated