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

# Error handling and status codes

> Understand Zerion API error responses, HTTP status codes, rate-limit errors, and best practices for retry logic and exponential backoff in production apps.

Zerion API uses standard HTTP status codes and returns structured error responses. This page covers what to expect and how to handle errors gracefully.

## Error response format

All errors return a JSON object with an `errors` array:

```json theme={null}
{
  "errors": [
    {
      "title": "Short error description",
      "detail": "A longer explanation of what went wrong"
    }
  ]
}
```

## HTTP status codes

| Status | Meaning | When it happens |
| - | - | - |
| `200` | Success | Request completed successfully |
| `400` | Bad Request | Malformed parameters - check filter values, missing required fields, or invalid formats |
| `401` | Unauthorized | Missing or invalid API key |
| `404` | Not Found | The requested resource doesn't exist (single-resource endpoints only) |
| `422` | Unprocessable Entity | The request cannot be served, and retrying will not change that |
| `429` | Too Many Requests | Rate limit exceeded |
| `500` | Server Error | Unexpected error on Zerion's side - safe to retry with backoff |
| `503` | Service Unavailable | Data is still being prepared - retry after the delay in the `Retry-After` header |

### 400 - Bad Request

Returned when query parameters are malformed or invalid. Check the `detail` field for specifics.

```json theme={null}
{
  "errors": [
    {
      "title": "Malformed parameter was sent",
      "detail": "chain {invalidchain} is not supported"
    }
  ]
}
```

**Common causes:**

* Invalid `filter[chain_ids]` value (e.g., a chain ID that doesn't exist)
* `page[size]` outside the allowed range (the maximum varies by endpoint)
* Missing required parameters (e.g., `filter[references]` on the NFTs endpoint)
* Malformed `filter[min_mined_at]` timestamp (must be exactly 13 digits, in milliseconds)
* An address Zerion doesn't track (see below)

#### Untracked addresses

The PnL, transactions and NFT endpoints only accept addresses that behave like user wallets, and reject anything else before doing any work:

```json theme={null}
{
  "errors": [
    {
      "title": "Malformed parameter was sent",
      "detail": "address 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 is not trackable"
    }
  ]
}
```

Rejected: contracts that aren't recognized smart-contract wallets (token contracts, routers, vaults), burn and reserved addresses, and high-volume addresses such as exchange hot wallets and mining pools. Smart-contract wallets are fine: Safe, Coinbase Smart Wallet, ERC-4337 accounts and EIP-7702 delegated EOAs all work.

Recognition works by wallet implementation, so a newly deployed Safe is tracked immediately with no setup. Trackability is decided per address, not per chain. If you need a specific address, or a wallet implementation we don't recognize yet, contact support.

### 401 - Unauthorized

Returned when the API key is missing, invalid, or incorrectly encoded.

```json theme={null}
{
  "errors": [
    {
      "title": "Unauthorized Error",
      "detail": "The API key is invalid, please, make sure that you are using a valid key"
    }
  ]
}
```

**Common causes:**

* Missing `Authorization` header
* API key not Base64-encoded correctly - remember to append a colon: `base64("your_key:")`
* Expired or revoked API key

<Tip>
  Test your encoding: `echo -n "your_api_key:" | base64` should produce the value you pass after `Basic `.
</Tip>

### 404 - Not Found

Returned on single-resource endpoints when the ID doesn't match any record.

```json theme={null}
{
  "errors": [
    {
      "title": "Requested fungible was not found",
      "detail": "You have requested fungible which does not exist"
    }
  ]
}
```

This only applies to endpoints like `/v1/fungibles/{fungible_id}` or `/v1/nfts/{nft_id}`. List endpoints return an empty `data` array instead of a 404.

### 422 - Unprocessable Entity

Returned when a request cannot be served and retrying will not change that. Unlike a `503`, it carries no `Retry-After` header.

```json theme={null}
{
  "errors": [
    {
      "title": "This request is not supported",
      "detail": "This request cannot be processed, and retrying will not help. Please contact support if you need it enabled."
    }
  ]
}
```

The PnL endpoints (`/v1/wallets/{address}/pnl` and `/v1/wallet-sets/pnl`) return it for wallets with more than 1 million actions, which are too large for PnL to be calculated. The limit is counted per address, so a wallet set fails if any one of its addresses is over it.

Don't retry, and don't cache the result against the address: the same address can return a different status later.

### 429 - Too Many Requests

Returned when you exceed your plan's rate limit.

```json theme={null}
{
  "errors": [
    {
      "title": "Too many requests",
      "detail": "Your request had been throttled"
    }
  ]
}
```

Implement exponential backoff when retrying. For header details and retry guidance, see [Rate Limits](/rate-limits). If you're hitting limits consistently, upgrade your plan in the [Dashboard](https://dashboard.zerion.io).

### 500 - Server Error

Returned when something unexpected goes wrong on Zerion's side.

```json theme={null}
{
  "errors": [
    {
      "title": "Internal Server Error",
      "detail": "An unexpected error occurred"
    }
  ]
}
```

These errors are safe to retry. Use exponential backoff (e.g., 1s, 2s, 4s) and cap your retries. If the error persists, reach out to support.

### 503 - Service Unavailable

Returned when the data you asked for is still being prepared. The PnL, wallet positions and fungible chart endpoints compute a wallet's state on the first request, and answer with a `503` while that runs.

```json theme={null}
{
  "errors": [
    {
      "title": "Service is temporarily unavailable",
      "detail": "Please, retry later (check the Retry-After header)"
    }
  ]
}
```

This always includes a `Retry-After` header, typically 10 seconds. Wait for it rather than retrying immediately, and cap your attempts.

## Best practices

* **Retry on `429`, `500` and `503`.** Do not retry `400`, `401` or `422` - these return the same result however many times you send them.
* **Respect `Retry-After`.** On a `503` it tells you how long the data needs; retrying sooner burns your rate limit.
* **Use exponential backoff.** When retrying, increase the delay between attempts exponentially (e.g., 1s, 2s, 4s) to avoid overwhelming the API.
* **Validate parameters before sending.** Check that `page[size]` is within the endpoint's allowed range, timestamps are 13-digit milliseconds, and chain IDs match the [supported chains](/supported-blockchains). This avoids unnecessary `400` errors.
* **Use webhooks instead of polling.** If you need to monitor wallet activity, use [transaction subscriptions](/api-reference/subscriptions-to-transactions/create-subscription) instead of polling. This reduces API usage and gives you faster notifications.


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