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

# Errors

> HTTP errors, validation failures, and retry guidance

## HTTP status codes

| Status      | Meaning                                                                           |
| ----------- | --------------------------------------------------------------------------------- |
| `200`–`299` | Successful request.                                                               |
| `400`       | Missing, invalid, or conflicting parameters.                                      |
| `401`       | Missing or invalid credential.                                                    |
| `403`       | Credential lacks permission or a publishable key attempted a protected operation. |
| `404`       | Resource was not found within the authenticated organization.                     |
| `409`       | Idempotency key or resource-state conflict.                                       |
| `422`       | Request is syntactically valid but violates a product rule.                       |
| `429`       | Request was rate limited.                                                         |
| `503`       | Temporary dependency, lock, or service failure.                                   |

## Response shape

Endpoints return a short error description and may include a stable code or additional fields:

```json theme={null}
{
  "error": "insufficient credits",
  "code": "insufficient_credits"
}
```

Do not parse human-readable text when a machine-readable `code` is available.

## Retry guidance

* Retry read requests only within your latency and request budget.
* Retry idempotent mutations with the same idempotency key and payload.
* Retry events with the same transaction ID.
* Honor `Retry-After` when returned.
* Do not retry validation, authorization, or insufficient-credit decisions without changing the underlying state.

## Common failures

| Error                   | Check                                                             |
| ----------------------- | ----------------------------------------------------------------- |
| Invalid API key         | Key prefix, revocation state, and target environment.             |
| Customer not found      | Server-owned external customer mapping and organization scope.    |
| Feature not found       | Feature code and plan entitlement configuration.                  |
| Subscription not active | Checkout payment state and subscription boundary.                 |
| Insufficient credits    | Effective balance, source expiry, Entity status, and pool policy. |