Errors

The Voucherify API uses conventional HTTP status codes to indicate success or failure. Responses with a status code starting with 4xx or 5xx can be considered as failed. The API returns errors in JSON format in the following structure:

{
  "code": 405,
  "message": "HTTP Method Not Allowed",
  "details": "PUT is not supported by this endpoint. Did you mean GET or POST?"
}

📘

Developer-friendly API

Voucherify attempts to provide a developer-friendly API, hence sometimes you can find a hint on how to fix an error right in its details (like in the example above).

ATTRIBUTES

code

The HTTP status code of error returned. Can be: 2xx, 4xx or 5xx.

key

For API object errors, a short string from the list on the right hand side, describing the kind of error which occurred.

message

A human-readable message providing short description about the error.

details

A human-readable message providing more details about the error.

HTTP status code summary

HTTP Status Code

Text

Description

400

Bad Request

The request was invalid. It may occur for various reasons - a malformed JSON or a violated rule (e.g. an attempt to redeem an expired voucher).

401

Unauthorized

Authentication has failed or has not been provided yet.

402

Payment Required

The request exceeded your current pricing plan (we send friendly reminders first).

404

Not Found

The requested resource could not be found.

405

Method Not Allowed

The request used a method (GET, POST, etc.) that is not available for given resource. Error details include a hint on which methods are allowed.

406

Not Acceptable

The API is unable to produce a response in a format specified by the Accept header. In most cases the only available response format is application/json.

415

Unsupported Media Type

The API is unable to consume a request in a format specified by the Content-Type header.

429

Hourly API limit reached

Error occurs when you exceed you hourly limit of API calls or when your subscription plan has ended.

500

Internal Server Error

An internal API error occurred. Don't worry, we track and verify all such errors and try to react as asap as possible.

resource_not_found

voucher with given code does not exist

voucher_not_active

voucher is not active yet (before start date)

voucher_expired

voucher has already expired (after expiration date)

voucher_disabled

voucher has been disabled (active: false)

quantity_exceeded

voucher's redemptions limit has been exceeded

gift_amount_exceeded

gift amount has been exceeded

customer_rules_violated

customer did not match to the segment

order_rules_violated

order did not match validation rules

invalid_order

order was specified incorrectly

invalid_payload

a request body is invalid and cannot be processed

invalid_amount

order amount was specified incorrectly

missing_amount

order amount was not specified

missing_order_items

order items was not specified

missing_customer

customer was not specified

already_rolled_back

redemption was rolled back before the current operation start time

invalid_voucher

voucher object was specified incorrectly (e.g., gift or discount is missing)

invalid_gift

gift object was specified incorrectly

duplicate_resource_key

resource identifier is in use

no_voucher_suitable_for_publication

lack of vouchers suitable for publication

invalid_add_balance_params

balance object was specified incorrectly

invalid_campaign_params

campaign object was specified incorrectly

invalid_code_config

voucher code configuration object was specified incorrectly

invalid_customer

customer object was specified incorrectly

invalid_export_params

export object was specified incorrectly

invalid_order

order object was specified incorrectly

invalid_product

product object was specified incorrectly

invalid_publish_params

publication object was specified incorrectly

invalid_rollback_params

redemption rollback object was specified incorrectly

invalid_sku

SKU object was specified incorrectly

invalid_validation_rules

validation rules object was specified incorrectly

invalid_query_params

input request query parameters are invalid

not_found

resource with given ID/code does not exist

Custom error messages with Validation Rules

Voucherify allows you to define your custom error message per Validation Rule; such message is going to be returned in API Response when validation or redemption of your promotion campaign or code fails due to not meeting requirements of that rule.
Additionally, you can specify a fallback error message that should be used when there is no error message defined for the rule.
You can define your custom error message both from our API or our Dashboard.

The content of custom error message is going to be returned in error object under message property.
If you do not specify any error message for your Validation Rule then error property will not be included in the API response.

Example:

Let's assume that you create a new Validation Rule via API and would like to have a custom error message "You can't get a discount because you are not new customer" returned from API.
The second condition says that your customer who is validating a voucher is not a new one (for that, we are going to use a segment represented by ID: seg_n3vVcU5t0m3rs4rEPr3C1oU5).
Additionally, you wish that the customer cart must contain an iPhone (prod_f1r5Tpr0DuC7 is our iPhone), and if not, then a fallback error message should be used: "You must buy iPhone and be our new customer to get a discount."
Let's examine how a request for creating such Validation Rule would look like, later we are also going to explore in details how API response is going to look:

{
  "name": "My validation rule",
  "error": {
    "message": "You must buy IPhone and be our new customer in order to get a discount"
  },
  "rules": {
    "1": {
      "name": "customer.segment",
      "conditions": {
        "$is": ["seg_n3vVcU5t0m3rs4rEPr3C1oU5"]
      },
      "error": {
        "message": "You can't get discount because you are not new customer"
      },
      "rules": {}
    },
    "2": {
        "name": "product.id",
        "conditions": {
            "$is": [{
                "id": "prod_f1r5Tpr0DuC7"
            }]
        },
        "rules": {}
    },
    "logic": "1 AND 2"
  }
}

As you can see in request body above, there is error property defined on top level which is going to serve as an fallback. There is also error message set per rule which is going to be returned in API response when validation / redemption fail due to that specific rule.

Let's see below how API Response is going to look in different scenarios when validation voucher:

Provided IPhone in order but provided customer does not belong to required segment:

{
    "code": "MY-TEST-CODE",
    "valid": false,
    "reason": "customer does not match segment rules",
    "tracking_id": "track_BRR0eIl/xcEftRmZCj65AQ==",
    "metadata": {},
    "error": {
        "message": "You can't get discount because you are not new customer"
    }
}

Provided customer belongs to required segment, but the IPhone was not specified in order:

{
    "code": "MY-TEST-CODE",
    "valid": false,
    "reason": "order does not match validation rules",
    "tracking_id": "track_BRR0eIl/xcFGi+qDwBt2E8W3LQP5W8Np",
    "metadata": {},
    "error": {
        "message": "You must buy IPhone and be our new customer in order to get a discount"
    }
}

Passing both checks - providing customer who belongs to required segment and IPhone is part of an order:

{
    "code": "MY-TEST-CODE",
    "valid": true,
    "discount": {
        "type": "AMOUNT",
        "amount_off": 10000
    },
    "order": {
        "object": "order",
        "items": [
            {
                "object": "order_item",
                "product_id": "prod_f1r5Tpr0DuC7",
                "quantity": 1
            }
        ]
    },
    "tracking_id": "track_BRR0eIl/xcFGi+qDwBt2E8W3LQP5W8Np",
    "metadata": {}
}