Errors - VoucherGrid

The Developer API uses standard HTTP status codes. Error responses are JSON objects with a single detail field describing what went wrong.

{
  "detail": "Voucher not found"
}

For 422 validation errors (request body or query parameter shape mismatch), detail is an array describing each invalid field – this is FastAPI’s HTTPValidationError shape:

{
  "detail": [
    {
      "loc": ["body", "amount"],
      "msg": "Input should be greater than 0",
      "type": "greater_than"
    }
  ]
}

Status codes

Status	When you’ll see it
200	Successful read or update
201	Resource created (`POST /vouchers`, `POST /customers`)
400	Invalid status filter value, invalid voucher state for redemption, redemption amount exceeds balance
401	API key missing, invalid, revoked, or expired
403	Tenant account disabled, subscription not Professional, location mismatch, or missing scope
404	Voucher / product / customer / location not found within your tenant
409	Customer email conflict, idempotency key replay still in flight, or concurrent voucher balance change
422	Request body or query parameter failed validation
429	Rate limit exceeded – see Rate limits

Endpoint-specific 400 messages

The redemption endpoint returns 400 with one of these detail strings:

"Voucher is pending and not redeemable" – voucher status is pending.
"Voucher is not redeemable" – status is redeemed, expired, voided, or refunded.
"Cannot redeem an expired voucher" – expiry_date is in the past.
"Redemption amount exceeds available balance" – amount > balance.