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 a 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).

HTTP status code summary

Error Messages

The table below shows a list of errors that may be returned along with a brief description of the reason why it occurs.

🚧

Customize Error Messages

A subset of the messages returned for the errors listed below can be customized in the UI.

Go to Project Settings > Error Messages to customize an error message. Then click on Create new translations group to create specific error messages. Read more here.

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 the API or your 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 a 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 an error property defined at the top level which is going to serve as a fallback. There is also an error message set per rule which is going to be returned in the API response when validation / redemption fail due to that specific rule.

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

Provided required iPhone in order but the 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 a new customer"
    }
}

Provided customer belongs to required segment, but the iPhone was not specified in the 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 the required segment and items list with iPhone:

{
    "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": {}
}