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

# Errors

> The error format, every error code, and which errors to retry.

Errors use HTTP status codes and an [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) `application/problem+json` body:

```json theme={null}
{
  "type": "https://invoice.horizonpay.co/problems/invalid-state",
  "title": "Invalid state for this operation",
  "status": 409,
  "detail": "This invoice has been finalized and can no longer be edited.",
  "instance": "req_4f0c2a9e8b7d4c1fa3e2b6d9c0e1f2a3",
  "code": "invalid_state"
}
```

* **Branch on `code`.** The wording of `detail` can change.
* **`instance`** is the request id, also sent as the `X-Request-Id` header. Include it when you contact support. You can send your own `X-Request-Id` (up to 200 characters) and it's echoed back.
* **`errors`** appears on `422` responses: a list of `{ "path", "message" }`, such as `{ "path": "items.0.unit_amount", "message": "Use whole minor units" }`.

## Error codes

| `code` | Status | Retry? | Meaning |
| - | - | - | - |
| `validation` | `422` | No | A field or query parameter is invalid. See `errors`. |
| `idempotency_mismatch` | `422` | No | An `Idempotency-Key` was reused with a different request. |
| `unauthorized` | `401` | No | The API key is missing, invalid, revoked or expired. |
| `forbidden` | `403` | No | The key lacks the scope this endpoint needs. |
| `not_found` | `404` | No | No such resource, or the id is malformed. |
| `invalid_state` | `409` | No | The resource is in the wrong state, such as editing a finalized invoice. |
| `conflict` | `409` | Yes | A request with the same `Idempotency-Key` is still running, or a write clashed with another one. |
| `idempotency_key_required` | `428` | No | This endpoint needs an `Idempotency-Key` header. |
| `rate_limited` | `429` | After `Retry-After` | You hit a [rate limit](/rate-limits). |
| `internal_error` | `500` | Yes | Something went wrong on our side. |
| `upstream_failed` | `502` | Yes | A service we depend on failed: the email provider or the database. |

Also retry network errors and timeouts. When you retry a write, reuse the same [`Idempotency-Key`](/idempotency). The [SDKs](/sdks/node#errors-and-retries) retry for you.

<Note>
  A `502` from `POST /invoices/{id}/send` can arrive **after** the invoice was finalized. The invoice keeps its number, and an `invoice.email_failed` event is recorded. Retry the send.
</Note>


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