Vouchers API Error Codes

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:

{
  "status": 404,
  "code": "VOUCHER.NOT_FOUND",
  "message": "The requested Voucher was not found."
}

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

{
  "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.

Response Format

Validation Error Codes

Client

Connect

Voucher

Create

Delete

Recharge

Status

Update

VoucherCharge

Refund

VoucherReservation

Create

Charge

General error codes

VoucherReservation

Create

What’s Next?

Vouchers API Quickstart

Voucher API Reference

​Response Format

​Validation Error Codes

​Client

​Connect

​Voucher

​Create

​Delete

​Recharge

​Status

​Update

​VoucherCharge

​Refund

​VoucherReservation

​Create

​Charge

​General error codes

​VoucherReservation

​Create

​What’s Next?

Vouchers API Quickstart

Voucher API Reference

Response Format

Validation Error Codes

Client

Connect

Voucher

Create

Delete

Recharge

Status

Update

VoucherCharge

Refund

VoucherReservation

Create

Charge

General error codes

VoucherReservation

Create

What’s Next?