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

HTTP Status CodeExplanation
200 OKThe request was successful. Please note the operation may have partial errors. For instance, when redeeming multiple coupon codes or promotions in one request, one or more of the codes may fail while the rest succeed.
201 CreatedThe requested resource was created.
202 AcceptedThe request has been accepted and will be processed.
400 Bad requestThe request was unsuccessful.
401 UnauthorisedInvalid or missing credentials.
403 ForbiddenOperation is forbidden to your account.
404 Not foundA resource was not found.
429 Too many requestsRate limited.
5xxInternal server errors.

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

Error Structure


{
  "id": "string",
  "message": "string",
  "reference": "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.

Error IDHTTP CodeDescriptionAccepts Translation
code_deactivated200The code cannot be used because it is deactivated.Yes
code_expired200The code cannot be used because it has expired due to dynamic code expiry.Yes
code_locked200Validation lock is in effect on this code and the unlock parameter has not been given or it is invalid.Yes
code_redeemed200Code cannot be used because it has been redeemed already.Yes
master_code_cannot_be_used200A request was made to apply the master code of the promotion instead of a unique/secure code.Yes
missing_linked_unique_reference200The expected linked unique reference for a secure code promotion was not provided.Yes
promotion_inaccessible_by_distributor400This distributor account has no access to claim codes for this promotion.Yes
unique_coupon_code_not_found404This error is returned by a single-resource endpoint such as /v2/deactivate when the code is not found.Yes
unsupported_distribution_method400A request to claim a code occurred (/v2/claims) for a promotion that has been set up to use external merchant codes. For these promotions, the codes are not distributed from Uniqodo.Yes
resource_not_found404 if a single resource has been requested otherwise 200 for multiple resourcesA required resource cannot be found. The resource could refer to a code or a promotion. For example, when a promotion application request is made for a code that does not exist this error will be returned.Yes
coupon_code_per_order_limit_reached200A promotion application request tried to apply more codes than allowed per order. This is configurable by Admin users through Uniqodo's interface in Promotion Combination settings.Yes
max_applied_promotions_reached200The maximum number of applied promotions has been reached for this order.Yes
max_automatic_promotions_reached200The maximum number of automatic promotions has been reached for this order.Yes
promotion_already_applied200Promotion has already been applied once in the order.Yes
custom_rule_violation200A validation rule for the promotion is not met. These errors are promotion-specific and can be configured when a promotion is created.Yes
automatic_promotion_cannot_claim_code400Promotions with the application method set to automatic cannot claim codes. This error will be returned if a call to /v2/claims happens for an automatic promotion.Yes
incorrect_linked_unique_reference200An incorrect linked unique reference has been provided while trying to apply for a secure code promotion.Yes
missing_required_code200The given promotion needs to be applied by use of a code and not promotionId (promotion application method set to Code).Yes
promotion_combination_not_allowed200Promotion Combination is not allowed, only one promotion can be applied in the orderYes
promotion_has_expired400 if a single resource has been requested otherwise 200 for multiple resourcesThe promotion end date has passed and the promotion has expired.Yes
promotion_is_inactive400 if a single resource has been requested otherwise 200 for multiple resourcesThe promotion is not active. This status includes scheduled, paused, archived or not yet approved promotions.Yes
promotion_is_repeat_code400The promotion is a repeat code promotion therefore codes cannot be claimed for that promotion. This occurs if a call is made to /v2/claims for a repeat code promotion.Yes
promotion_not_accessible400The promotion is not accessible with the authentication credentials that have been provided. This error will be returned if a call to /v2/claims happens for a promotion that the distributor has no access to.Yes
redemption_limit_reached400 if a single resource has been requested otherwise 200 for multiple resourcesThe maximum number of redemptions for this promotion has reached the configured limit. No more codes of that promotion can be applied to an order or issued.Yes
repeat_code_does_not_belong_to_promotion200The repeat code given is not one of the master codes of the promotion.Yes
secure_code_user_email_required400A request to claim a code for a secure code promotion happened but the field linkedUniqueReference was not provided. This field is mandatory to be provided for secure code promotions.Yes
shopper_code_not_recognised200A repeat customer code (shopper code) was set up for this promotion but the one given was incorrect.Yes
authentication_failed401Invalid credentials have been provided and the request is not accepted. This error will always be returned with a 401 status code.No
malformed_request_payload400The request payload contains incorrect or malformed JSON. Please submit requests that conform to the JSON standard. This error is returned with a 400 status code always and stops any further processing of the request.No
request_parameter_error400The request contains schema errors and cannot be accepted. This error is returned with a 400 status code always and stops any further processing of the request.No
bundle_items_not_in_order200The order does not contain any of the product bundle items that have been set up for this promotion.Yes
full_discount_reached200The code or promotion cannot be applied as the order has reached the full discount (total is 0)Yes
full_shipping_discount_reached200The code or promotion cannot be applied as the possible reward is a shipping discount, however the shipping cost is already fully discounted.Yes
product_discount_not_applicable200The order does not contain any product that qualifies for a Product discount according to the set up for this promotion.Yes
promotion_cannot_be_combined200Promotion cannot be combined with the promotions that are already applied in the order. This is configurable by Admin users through Uniqodo's interface in Promotion Combination settings.Yes
technical_error400 if a single resource has been requested otherwise 200 for multiple resourcesA technical error has occurred. See the section on Technical Errors.Yes
request_not_completed500Uniqodo's server has failed. This error is returned with a 500 status code always.No
shipping_not_specified200Shipping information was not sent with the request and a shipping discount promotion was given to be applied.Yes

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.