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 Code | Explanation |
---|---|
200 OK | The 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 Created | The requested resource was created. |
202 Accepted | The request has been accepted and will be processed. |
400 Bad request | The request was unsuccessful. |
401 Unauthorised | Invalid or missing credentials. |
403 Forbidden | Operation is forbidden to your account. |
404 Not found | A resource was not found. |
429 Too many requests | Rate limited. |
5xx | Internal 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 ID | HTTP Code | Description | Accepts Translation |
---|---|---|---|
code_deactivated | 200 | The code cannot be used because it is deactivated. | Yes |
code_expired | 200 | The code cannot be used because it has expired due to dynamic code expiry. | Yes |
code_locked | 200 | Validation lock is in effect on this code and the unlock parameter has not been given or it is invalid. | Yes |
code_redeemed | 200 | Code cannot be used because it has been redeemed already. | Yes |
master_code_cannot_be_used | 200 | A request was made to apply the master code of the promotion instead of a unique/secure code. | Yes |
missing_linked_unique_reference | 200 | The expected linked unique reference for a secure code promotion was not provided. | Yes |
promotion_inaccessible_by_distributor | 400 | This distributor account has no access to claim codes for this promotion. | Yes |
unique_coupon_code_not_found | 404 | This error is returned by a single-resource endpoint such as /v2/deactivate when the code is not found. | Yes |
unsupported_distribution_method | 400 | A 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_found | 404 if a single resource has been requested otherwise 200 for multiple resources | A 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_reached | 200 | A 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_reached | 200 | The maximum number of applied promotions has been reached for this order. | Yes |
max_automatic_promotions_reached | 200 | The maximum number of automatic promotions has been reached for this order. | Yes |
promotion_already_applied | 200 | Promotion has already been applied once in the order. | Yes |
custom_rule_violation | 200 | A 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_code | 400 | Promotions 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_reference | 200 | An incorrect linked unique reference has been provided while trying to apply for a secure code promotion. | Yes |
missing_required_code | 200 | The given promotion needs to be applied by use of a code and not promotionId (promotion application method set to Code). | Yes |
promotion_combination_not_allowed | 200 | Promotion Combination is not allowed, only one promotion can be applied in the order | Yes |
promotion_has_expired | 400 if a single resource has been requested otherwise 200 for multiple resources | The promotion end date has passed and the promotion has expired. | Yes |
promotion_is_inactive | 400 if a single resource has been requested otherwise 200 for multiple resources | The promotion is not active. This status includes scheduled, paused, archived or not yet approved promotions. | Yes |
promotion_is_repeat_code | 400 | The 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_accessible | 400 | The 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_reached | 400 if a single resource has been requested otherwise 200 for multiple resources | The 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_promotion | 200 | The repeat code given is not one of the master codes of the promotion. | Yes |
secure_code_user_email_required | 400 | A 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_recognised | 200 | A repeat customer code (shopper code) was set up for this promotion but the one given was incorrect. | Yes |
authentication_failed | 401 | Invalid credentials have been provided and the request is not accepted. This error will always be returned with a 401 status code. | No |
malformed_request_payload | 400 | The 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_error | 400 | The 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_order | 200 | The order does not contain any of the product bundle items that have been set up for this promotion. | Yes |
full_discount_reached | 200 | The code or promotion cannot be applied as the order has reached the full discount (total is 0) | Yes |
full_shipping_discount_reached | 200 | The 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_applicable | 200 | The order does not contain any product that qualifies for a Product discount according to the set up for this promotion. | Yes |
promotion_cannot_be_combined | 200 | Promotion 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_error | 400 if a single resource has been requested otherwise 200 for multiple resources | A technical error has occurred. See the section on Technical Errors. | Yes |
request_not_completed | 500 | Uniqodo's server has failed. This error is returned with a 500 status code always. | No |
shipping_not_specified | 200 | Shipping 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.