Order Errors


Order Errors are errors that occur when attempting to interact with the external commerce platform. Some of these errors are self-resolving, while others require the developer to take further steps to remediate them.

When considering order errors, it's important to remember that checkout processes within Violet are currently handled in an asynchronous format. When a checkout-related request is sent through the Violet API, a subsequent request is sent to the external commerce platform, asynchronously. Violet returns a response consisting of an updated Violet order to the developer before receiving a response from the external commerce platform. In the event that an error occurs on the side of the external commerce platform, Violet will update the Violet order record with information about the error in the "errors":[] property. This means that a developer will not immediately see an error in the response from their request. Instead they must perform a GET cart by ID request to view their latest cart data and see if any errors exists, or submit the order, at which point any errors on the cart are surfaced and the order is not submitted until they are resolved.

Understanding Error Messages

Error messages are provided in the following format, nested in the "errors": [] property of the order entity.

  "errors": [{
    "id": 999,
    "order_id": 999,
    "bag_id": 999,
    "type": "EXTERNAL_ADD_ITEM",
    "message": "Not enough items available. Only 0 left",
    "date_created": "2021-01-20T00:00:00+0000",

id Unique ID of the error. Primarily useful as a reference.

order_id the ID of the order this error applies to.

bag_id the ID of the bag this error applies to.

entity_id the ID of the entity this error applies to. Will be null or not present if the error is not related to an entity. An example of an entity is a SKU. If an error occurred while adding, modifying, or removing a SKU, the SKU ID will be present here.

type A value that maps the error to the action that was being attempted at the time. These have a direct relationship to the checkout endpoints in the Violet API.


message A message that helps the developer better understand what happened. This is typically the error message from the commerce platform. In time these will be improved to be more uniform across all commerce platforms, with unprocessed messages being made available in a new raw_message property.


Moving Forward

There are currently two improvements on the roadmap for how to improve the developer experience when interacting with checkout errors.

Synchronous Requests
Channels will have the option of disabling the asynchronous functionality on a per-request basis. This means that anytime they wish to wait for the response from the commerce platform before completing their request they can tell Violet to do so, likely through a query param (async=false ) passed into each request.

Error Webhooks
Channels will be able to register webhooks and receive error data at an endpoint of their choosing. Receiving errors via webhooks will likely be slightly slower than through synchronous requests due to the extra hops. However, since they happen asynchronously the experience for the shopper will likely be faster as there is no waiting on the response from the commerce platform.