> ## Documentation Index
> Fetch the complete documentation index at: https://developer.jtl-software.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Vouchers API Error Codes

> Error response format and validation error codes for the Vouchers API.

The Vouchers API returns structured error objects on failed requests. This page covers the response format, validation error codes, and general business logic error codes.

## Response Format

Failed requests return an error object:

```json theme={null}
{
  "status": 404,
  "code": "VOUCHER.NOT_FOUND",
  "message": "The requested Voucher was not found."
}
```

`422 Unprocessable Entity` responses include a list of field-level errors:

```json theme={null}
{
  "status": 422,
  "code": "VOUCHER.CREATE.UNPROCESSABLE_ENTITY",
  "message": "The given data was invalid.",
  "errors": [
    {
      "code": "VOUCHER.CREATE.CURRENCY.VALID_CURRENCY",
      "property": "currency",
      "rule": "valid_currency",
      "message": "Currency must be a valid currency code"
    }
  ]
}
```

## Validation Error Codes

These appear in the `errors` array of `422` responses.

### Client

Errors returned when connecting a client.

#### Connect

| Code                          | Message                    |
| ----------------------------- | -------------------------- |
| `CLIENT.CONNECT.PIN.REQUIRED` | The pin field is required. |
| `CLIENT.CONNECT.PIN.STRING`   | The pin must be a string.  |

### Voucher

Errors returned when creating, updating, deleting, recharging, or changing the status of a voucher.

#### Create

| Code                                                               | Message                                                            |
| ------------------------------------------------------------------ | ------------------------------------------------------------------ |
| `VOUCHER.CREATE.CUSTOM_ID.STRING`                                  | The custom\_id must be a string.                                   |
| `VOUCHER.CREATE.CUSTOM_ID.MAX:255`                                 | The custom\_id may not be greater than 255 characters.             |
| `VOUCHER.CREATE.CUSTOM_ID.UNIQUE`                                  | The custom\_id has already been taken.                             |
| `VOUCHER.CREATE.CODE.STRING`                                       | The code must be a string.                                         |
| `VOUCHER.CREATE.CODE.MAX:255`                                      | The code may not be greater than 255 characters.                   |
| `VOUCHER.CREATE.CODE.UNIQUE`                                       | The code has already been taken.                                   |
| `VOUCHER.CREATE.SKU.STRING`                                        | The sku must be a string.                                          |
| `VOUCHER.CREATE.SKU.MAX:255`                                       | The sku may not be greater than 255 characters.                    |
| `VOUCHER.CREATE.PIN.STRING`                                        | The pin must be a string.                                          |
| `VOUCHER.CREATE.PIN.MAX:255`                                       | The pin may not be greater than 255 characters.                    |
| `VOUCHER.CREATE.BATCH.STRING`                                      | The batch must be a string.                                        |
| `VOUCHER.CREATE.BATCH.MAX:30`                                      | The batch may not be greater than 30 characters.                   |
| `VOUCHER.CREATE.AMOUNT.REQUIRED`                                   | The amount field is required.                                      |
| `VOUCHER.CREATE.AMOUNT.STRING`                                     | The amount must be a string.                                       |
| `VOUCHER.CREATE.AMOUNT.NUMERIC`                                    | The amount must be a number.                                       |
| `VOUCHER.CREATE.AMOUNT.MIN:0`                                      | The amount must be at least 0.                                     |
| `VOUCHER.CREATE.AMOUNT.VALID_CURRENCY_AMOUNT`                      | Amount must have exactly two decimals.                             |
| `VOUCHER.CREATE.STATUS.VALID_VOUCHER_STATUS`                       | Voucher status can only be: inactive, active.                      |
| `VOUCHER.CREATE.CURRENCY.REQUIRED`                                 | The currency field is required.                                    |
| `VOUCHER.CREATE.CURRENCY.VALID_CURRENCY`                           | Currency must be a valid currency code.                            |
| `VOUCHER.CREATE.VALIDITY_VALUE.NUMERIC`                            | The validity\_value must be a number.                              |
| `VOUCHER.CREATE.VALIDITY_VALUE.GT:0`                               | The validity\_value must be greater than 0.                        |
| `VOUCHER.CREATE.VALIDITY_INTERVAL.STRING`                          | The validity\_interval must be a string.                           |
| `VOUCHER.CREATE.VALIDITY_INTERVAL.VALID_VOUCHER_VALIDITY_INTERVAL` | Voucher validity interval can only be: days, weeks, months, years. |
| `VOUCHER.CREATE.TYPE.VALID_VOUCHER_TYPE`                           | Voucher types can only be: print, digital.                         |
| `VOUCHER.CREATE.TAXABLE.BOOLEAN`                                   | The taxable field must be true or false.                           |
| `VOUCHER.CREATE.TAX_RATE.REQUIRED_IF:TAXABLE,TRUE`                 | The tax\_rate field is required when taxable is true.              |
| `VOUCHER.CREATE.TAX_RATE.NUMERIC`                                  | The tax\_rate must be a number.                                    |
| `VOUCHER.CREATE.TAX_RATE.BETWEEN:0,100`                            | The tax\_rate must be between 0 and 100.                           |
| `VOUCHER.CREATE.ORDER_NUMBER.STRING`                               | The order\_number must be a string.                                |
| `VOUCHER.CREATE.ORDER_NUMBER.MAX:255`                              | The order\_number may not be greater than 255 characters.          |
| `VOUCHER.CREATE.DATA.JSON`                                         | The data must be a valid JSON string.                              |

#### Delete

| Code                              | Message                                             |
| --------------------------------- | --------------------------------------------------- |
| `VOUCHER.DELETE.COMMENT.REQUIRED` | The comment field is required.                      |
| `VOUCHER.DELETE.COMMENT.STRING`   | The comment must be a string.                       |
| `VOUCHER.DELETE.COMMENT.MAX:255`  | The comment may not be greater than 255 characters. |

#### Recharge

| Code                                            | Message                                    |
| ----------------------------------------------- | ------------------------------------------ |
| `VOUCHER.RECHARGE.AMOUNT.REQUIRED`              | The amount field is required.              |
| `VOUCHER.RECHARGE.AMOUNT.STRING`                | The amount must be a string.               |
| `VOUCHER.RECHARGE.AMOUNT.NUMERIC`               | The amount must be a number.               |
| `VOUCHER.RECHARGE.AMOUNT.BETWEEN:0.01,99999`    | The amount must be between 0.01 and 99999. |
| `VOUCHER.RECHARGE.AMOUNT.VALID_CURRENCY_AMOUNT` | Amount must have exactly two decimals.     |
| `VOUCHER.RECHARGE.CURRENCY.REQUIRED`            | The currency field is required.            |
| `VOUCHER.RECHARGE.CURRENCY.VALID_CURRENCY`      | Currency must be a valid currency code.    |
| `VOUCHER.RECHARGE.ORDER_NUMBER.REQUIRED`        | The order\_number field is required.       |
| `VOUCHER.RECHARGE.ORDER_NUMBER.STRING`          | The order\_number must be a string.        |

#### Status

| Code                                         | Message                                       |
| -------------------------------------------- | --------------------------------------------- |
| `VOUCHER.STATUS.STATUS.REQUIRED`             | The status field is required.                 |
| `VOUCHER.STATUS.STATUS.VALID_VOUCHER_STATUS` | Voucher status can only be: inactive, active. |

#### Update

| Code                                                               | Message                                                            |
| ------------------------------------------------------------------ | ------------------------------------------------------------------ |
| `VOUCHER.UPDATE.CUSTOM_ID.STRING`                                  | The custom\_id must be a string.                                   |
| `VOUCHER.UPDATE.CUSTOM_ID.MAX:255`                                 | The custom\_id may not be greater than 255 characters.             |
| `VOUCHER.UPDATE.CUSTOM_ID.UNIQUE`                                  | The custom\_id has already been taken.                             |
| `VOUCHER.UPDATE.CODE.STRING`                                       | The code must be a string.                                         |
| `VOUCHER.UPDATE.CODE.MAX:255`                                      | The code may not be greater than 255 characters.                   |
| `VOUCHER.UPDATE.CODE.UNIQUE`                                       | The code has already been taken.                                   |
| `VOUCHER.UPDATE.SKU.STRING`                                        | The sku must be a string.                                          |
| `VOUCHER.UPDATE.SKU.MAX:255`                                       | The sku may not be greater than 255 characters.                    |
| `VOUCHER.UPDATE.PIN.STRING`                                        | The pin must be a string.                                          |
| `VOUCHER.UPDATE.PIN.MAX:255`                                       | The pin may not be greater than 255 characters.                    |
| `VOUCHER.UPDATE.BATCH.STRING`                                      | The batch must be a string.                                        |
| `VOUCHER.UPDATE.BATCH.MAX:30`                                      | The batch may not be greater than 30 characters.                   |
| `VOUCHER.UPDATE.AMOUNT.STRING`                                     | The amount must be a string.                                       |
| `VOUCHER.UPDATE.AMOUNT.NUMERIC`                                    | The amount must be a number.                                       |
| `VOUCHER.UPDATE.AMOUNT.MIN:0`                                      | The amount must be at least 0.                                     |
| `VOUCHER.UPDATE.AMOUNT.VALID_CURRENCY_AMOUNT`                      | Amount must have exactly two decimals.                             |
| `VOUCHER.UPDATE.STATUS.VALID_VOUCHER_STATUS`                       | Voucher status can only be: inactive, active.                      |
| `VOUCHER.UPDATE.CURRENCY.VALID_CURRENCY`                           | Currency must be a valid currency code.                            |
| `VOUCHER.UPDATE.VALIDITY_VALUE.NUMERIC`                            | The validity\_value must be a number.                              |
| `VOUCHER.UPDATE.VALIDITY_INTERVAL.STRING`                          | The validity\_interval must be a string.                           |
| `VOUCHER.UPDATE.VALIDITY_INTERVAL.VALID_VOUCHER_VALIDITY_INTERVAL` | Voucher validity interval can only be: days, weeks, months, years. |
| `VOUCHER.UPDATE.TYPE.VALID_VOUCHER_TYPE`                           | Voucher types can only be: print, digital.                         |
| `VOUCHER.UPDATE.TAXABLE.BOOLEAN`                                   | The taxable field must be true or false.                           |
| `VOUCHER.UPDATE.TAX_RATE.REQUIRED_IF:TAXABLE,TRUE`                 | The tax\_rate field is required when taxable is true.              |
| `VOUCHER.UPDATE.TAX_RATE.NUMERIC`                                  | The tax\_rate must be a number.                                    |
| `VOUCHER.UPDATE.TAX_RATE.BETWEEN:0,100`                            | The tax\_rate must be between 0 and 100.                           |
| `VOUCHER.UPDATE.ORDER_NUMBER.STRING`                               | The order\_number must be a string.                                |
| `VOUCHER.UPDATE.ORDER_NUMBER.MAX:255`                              | The order\_number may not be greater than 255 characters.          |
| `VOUCHER.UPDATE.DATA.JSON`                                         | The data must be a valid JSON string.                              |

### VoucherCharge

Errors returned when refunding a charge.

#### Refund

| Code                                                | Message                                                 |
| --------------------------------------------------- | ------------------------------------------------------- |
| `VOUCHERCHARGE.REFUND.AMOUNT.REQUIRED`              | The amount field is required.                           |
| `VOUCHERCHARGE.REFUND.AMOUNT.STRING`                | The amount must be a string.                            |
| `VOUCHERCHARGE.REFUND.AMOUNT.NUMERIC`               | The amount must be a number.                            |
| `VOUCHERCHARGE.REFUND.AMOUNT.BETWEEN:0.01,0`        | The amount must be between 0.01 and the charged amount. |
| `VOUCHERCHARGE.REFUND.AMOUNT.VALID_CURRENCY_AMOUNT` | Amount must have exactly two decimals.                  |
| `VOUCHERCHARGE.REFUND.CURRENCY.REQUIRED`            | The currency field is required.                         |
| `VOUCHERCHARGE.REFUND.CURRENCY.VALID_CURRENCY`      | Currency must be a valid currency code.                 |

### VoucherReservation

Errors returned when creating or charging a reservation.

#### Create

| Code                                                      | Message                                        |
| --------------------------------------------------------- | ---------------------------------------------- |
| `VOUCHERRESERVATION.CREATE.AMOUNT.REQUIRED`               | The amount field is required.                  |
| `VOUCHERRESERVATION.CREATE.AMOUNT.STRING`                 | The amount must be a string.                   |
| `VOUCHERRESERVATION.CREATE.AMOUNT.NUMERIC`                | The amount must be a number.                   |
| `VOUCHERRESERVATION.CREATE.AMOUNT.BETWEEN:0.01,99999`     | The amount must be between 0.01 and 99999.     |
| `VOUCHERRESERVATION.CREATE.AMOUNT.VALID_CURRENCY_AMOUNT`  | Amount must have exactly two decimals.         |
| `VOUCHERRESERVATION.CREATE.CODE.REQUIRED`                 | The code field is required.                    |
| `VOUCHERRESERVATION.CREATE.CODE.STRING`                   | The code must be a string.                     |
| `VOUCHERRESERVATION.CREATE.CODE.VALID_VOUCHER_CODE`       | Invalid voucher code.                          |
| `VOUCHERRESERVATION.CREATE.CODE.VALID_CLIENT_DESTINATION` | The client is not allowed to use this voucher. |
| `VOUCHERRESERVATION.CREATE.PIN.VALID_VOUCHER_PIN`         | Invalid voucher pin.                           |
| `VOUCHERRESERVATION.CREATE.CURRENCY.REQUIRED`             | The currency field is required.                |
| `VOUCHERRESERVATION.CREATE.CURRENCY.VALID_CURRENCY`       | Currency must be a valid currency code.        |

#### Charge

| Code                                              | Message                              |
| ------------------------------------------------- | ------------------------------------ |
| `VOUCHERRESERVATION.CHARGE.ORDER_NUMBER.REQUIRED` | The order\_number field is required. |
| `VOUCHERRESERVATION.CHARGE.ORDER_NUMBER.STRING`   | The order\_number must be a string.  |

## General error codes

These appear at the top level (not in `errors`) for business logic failures.

### VoucherReservation

#### Create

| Code                                  | Message                          |
| ------------------------------------- | -------------------------------- |
| `VOUCHERRESERVATION.CREATE.INACTIVE`  | This voucher is inactive.        |
| `VOUCHERRESERVATION.CREATE.EXPIRED`   | This voucher is expired.         |
| `VOUCHERRESERVATION.CREATE.NO_CREDIT` | This voucher has no credit left. |

***

## What's Next?

<CardGroup cols={2}>
  <Card title="Vouchers API Quickstart" icon="ticket" href="/guides/voucher/quickstart">
    Set up a client, get credentials, and run the full voucher lifecycle.
  </Card>

  <Card title="Voucher API Reference" icon="code" href="/api-reference/voucher">
    Full endpoint reference for all Vouchers API operations and parameters.
  </Card>
</CardGroup>