The Zerion API uses standard HTTP status codes and returns structured error responses. This page covers what to expect and how to handle errors gracefully.
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 |
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) |
429 | Too Many Requests | Rate limit exceeded |
500 | Server Error | Unexpected error on Zerion’s side — safe to retry with backoff |
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"
}
]
}
- 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)
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"
}
]
}
- 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"
}
]
}
/v1/fungibles/{fungible_id} or /v1/nfts/{nft_id}. List endpoints return an empty data array instead of a 404.
429 — Too Many Requests
Returned when you exceed your plan’s rate limit.
{
"errors": [
{
"title": "Too many requests",
"detail": "Your request had been throttled"
}
]
}
500 — Server Error
Returned when something unexpected goes wrong on Zerion’s side.
{
"errors": [
{
"title": "Internal Server Error",
"detail": "An unexpected error occurred"
}
]
}
Best practices
- Retry on
429 and 500 only. Do not retry 400 or 401 — these require fixing the request itself.
- 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.
