> For the complete documentation index, see [llms.txt](https://docs.blockz.fi/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.blockz.fi/api/errors.md).

# Errors

The Blockz API returns errors in a consistent JSON format. Each error includes:

* `code` (numeric error identifier)
* `message` (human-readable summary)
* `entity` (the related domain object, when applicable)

#### Error Response Format:

```json
{
  "code": 1,
  "message": "Internal server error",
  "entity": "Intent"
}
```

#### Error codes

| Code | Message                                 | Description / Notes                                     |
| ---- | --------------------------------------- | ------------------------------------------------------- |
| 2    | Unexpected swap status                  | Swap is in an invalid state for the requested operation |
| 3    | Serde error                             | Failed to serialize or deserialize data                 |
| 4    | Messaging error                         | Issue with internal messaging or event system           |
| 6    | Base58 error                            | Base58 encoding/decoding failed                         |
| 7    | Not found                               | Requested resource does not exist                       |
| 8    | Hex error                               | Hex encoding/decoding failed                            |
| 10   | Approval error                          | Error during approval process                           |
| 11   | Permit2 error                           | Failed to generate or validate Permit2 signature        |
| 12   | Intent status error                     | Invalid or unavailable intent status                    |
| 13   | Missing context                         | Required request context missing                        |
| 14   | Malformed header                        | Invalid HTTP headers                                    |
| 15   | Serde server error                      | Server failed to serialize/deserialize                  |
| 16   | Token error                             | Invalid token or token mismatch                         |
| 17   | Resolver address error                  | Resolver address invalid or missing                     |
| 19   | Fulfillment request hash creation error | Failed to create fulfillment request hash               |
| 20   | Fulfillment request hash signing error  | Failed to sign fulfillment request hash                 |
| 22   | Incorrect swap type                     | Swap type does not match expected                       |
| 23   | Optimized swap unsupported              | Attempted optimized swap not supported                  |
| 24   | Provider error                          | External provider failed                                |
| 25   | Balance error                           | Insufficient balance                                    |
| 26   | Address validation failed               | User or contract address invalid                        |
| 27   | Slippage validation failed              | Provided slippage value invalid                         |
| 28   | Signature validation failed             | User or system signature invalid                        |
| 31   | Resolver public key error               | Resolver public key invalid or missing                  |
| 32   | Required public key missing             | Public key required but not provided                    |
| 33   | BTC transaction builder error           | Failed to build BTC transaction                         |
| 35   | Forbidden network pair                  | Swap between this source/dest network not allowed       |