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:
{ "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
202
Accepted
NFT endpoints only: the wallet’s NFTs are still being indexed. Retry with backoff until you get 200
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.
{ "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:
{ "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 Zerion doesn’t recognize yet, contact support.
401 - Unauthorized
Returned when the API key is missing, invalid, or incorrectly encoded.
{ "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
Test your encoding: echo -n "your_api_key:" | base64 should produce the value you pass after Basic .
404 - Not Found
Returned on single-resource endpoints when the ID doesn’t match any record.
{ "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.
{ "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.
{ "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. If you’re hitting limits consistently, upgrade your plan in the Dashboard.
500 - Server Error
Returned when something unexpected goes wrong on Zerion’s side.
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.
{ "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. This avoids unnecessary 400 errors.
Use webhooks instead of polling. If you need to monitor wallet activity, use transaction subscriptions instead of polling. This reduces API usage and gives you faster notifications.
Was this page helpful?
Assistant
Responses are generated using AI and may contain mistakes.