Errors

Generally, all Uniqodo APIs are using HTTP status codes to indicate the success (2xx) or failure (4xx) of a request or operation.

In the event of a request failure, the 'errors' field within the response will encompass the errors structured as described below. It's important to note that there may be errors present in the response that do not result in a request failure, and, in such instances, the status code will still fall within the '2xx' range.

Take the /v2/apply endpoint as an example. If an attempt is made to apply an expired promotion to a purchase, the response will fall within the 2xx status code range. However, the errors field will contain a single error stating that the promotion has expired. Conversely, if the same endpoint encounters a request with schema errors, such as missing required fields, the response will fall within the 4xx status code range, indicating an incomplete request.

This distinction in status codes and error handling ensures clarity in various error scenarios to facilitate effective troubleshooting and resolution.

Response HTTP Status Codes

All errors follow the error structure that can be found below.

Error Structure

{
  "id": "string",
  "message": "string",
  "promotionId": "string",
  "couponCode": "string"
}

The string in the message field will be translated if the request includes a locale property and error translation has been set up on the API account you are using.

Technical Errors Structure

Unlike other errors, Technical Errors (i.e. error object with IDtechnical_error)should not be displayed to customers. These errors typically indicate issues related to the configuration of promotions or rewards, and they can only be resolved by resolving the issue with the promotion or the integration itself. These errors are not customer-facing and are meant to be handled internally by the developers responsible for the integration.

{
  "id": "string",
  "message": "string",
  "reason": "string",
  "promotionId": "string",
  "couponCode": "string"
}

Instructions on how to fix the error through Uniqodo's interface can be found in the reason field.

Examples

HTTP 200 - Successful request with coupon error

"errors": [
  {
    "promotionId": "60c5ef375e987e3856862129b39290b3",
    "couponCode": "D4LP7K",
    "message": "This code has been redeemed.",
    "id": "code_redeemed",
  },
  ...
]

HTTP 400 Bad Request - Technical Error

"errors": [
        {
            "reason": "Missing custom attribute target value. ProductId : Product1",
            "promotionId": "60c5ef375e987e3856862129b39290b2",
            "couponCode": "4LPH8T",
            "message": "Unable to perform this operation.",
            "id": "technical_error",
        }
]

Errors Details

📘

Please note that HTTP 200 does not guarantee a successful operation on all resources or entities in the request. The resources that failed will generate errors which will be included in the response but the request HTTP code will still be 200. For instance, when applying two promotions to an order in one request, one or more of the promotions may fail to apply while the rest succeed. This may be because the customer only meets the criteria of one of the promotions.

Promotion ID and/or coupon code will be returned in the promotionId and couponCode fields respectively if they are available.

For promotion application, these errors might be returned referencing the new code or promotion ID according to the table. However, they might also be returned referencing codes or promotions from already applied promotions in the order (order.appliedPromotions). This ensures that the response is a valid application of any allowed number of promotions at the time that it was received.