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

# Errors

> Status codes and error response shape returned by the Developer API.

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

```json theme={null}
{
  "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:

```json theme={null}
{
  "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](/developer-api/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`.