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

# Errors

> The error shape, the codes you will see, and which ones to retry

Every error has the same shape, so one handler covers them all:

```json theme={null}
{
  "error": {
    "type": "request_error",
    "code": "invalid_field",
    "detail": "Request does not pass validation.",
    "errors": [
      { "field": "email", "message": "The email field is required." }
    ]
  },
  "meta": {
    "requestId": "req_…"
  }
}
```

* `code` is stable. Branch on it in your code.
* `detail` is a sentence for people. It may change, so don't match on it.
* `errors` lists each field that failed, on a `422`.

## Status codes

| Status | Means | What to do |
| - | - | - |
| `400` | The request was malformed, for example `invalid_cursor`. | Fix the request. |
| `401` | `authentication_failed`: the key is missing, wrong or revoked. | Check the key. |
| `402` | `insufficient_credit`: a credit hold the credit can't cover. | Stop the request. See [Credit holds](https://docs.bouclay.com/credits/holds.md). |
| `403` | `permission_denied`: a restricted key without the scope. | Add the scope named in `detail`. |
| `404` | `not_found`: no such object, or an early access feature not yet on for your account. | Check the id. |
| `409` | A conflict, such as `idempotency_conflict`, `subscription_suspended` or `spending_cap_reached`. | Read `code`; the object is in a state that refuses this. |
| `410` | An expired link, such as a portal session. | Make a new one. |
| `422` | `invalid_field` or a business rule, such as `meter_billed_elsewhere`. | Fix the fields listed in `errors`. |
| `429` | `rate_limited`. | Wait for `Retry-After` seconds, then retry. |
| `5xx` | Something went wrong on our side. | Retry with the same `Idempotency-Key`. |

## Retrying safely

Retry `429` and `5xx` responses, and network errors, with the **same** `Idempotency-Key` and a growing wait between tries. Bouclay replays the first answer if the request already went through, so a retry never does the work twice. Don't retry `4xx` errors other than `429` without changing the request: they will fail the same way.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.