# Errors

> HTTP status codes and Bolt error handling for API integrations.

Source: https://help.boltapp.com/api-reference/errors

Bolt uses standard HTTP status codes. Error responses include a JSON body with details when validation fails.

## Common status codes [#common-status-codes]

| Status | Action                                                                                                                                                                                                                         |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `400`  | Fix request parameters                                                                                                                                                                                                         |
| `401`  | Send the `X-API-Key` header. On `/v1/merchant/` this status means none arrived and the endpoint fell back to a session check (code `1015`); on `/v1/subscriptions/` and `/v3/` it also covers a key that was sent and rejected |
| `403`  | Check the key, not the signature. On `/v1/merchant/` the `X-API-Key` was rejected (code `1005`); otherwise you lack permission or scope (code `18`)                                                                            |
| `404`  | Confirm resource ID and environment                                                                                                                                                                                            |
| `422`  | Review field-level validation errors. Inbound HMAC signature failures also arrive here, as code `27`                                                                                                                           |
| `429`  | Back off and retry with exponential delay                                                                                                                                                                                      |
| `5xx`  | Retry; contact support if persistent                                                                                                                                                                                           |

Which status a missing `X-API-Key` produces depends on the endpoint, not only on the path prefix: `POST /v1/merchant/orders` answers `403` with `1005`, the same as an invalid key. See [Response codes](/api-reference/api-quickstart#response-codes) for the cases that differ.

## Idempotency [#idempotency]

Use idempotency keys on payment and order mutations where supported. See [Idempotency reference](https://help.boltapp.com/developers/references/idempotency/).

## Full error catalog [#full-error-catalog]

See [Bolt error codes](https://help.boltapp.com/developers/error-codes/) for the complete list.