Skip to main content

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.

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.

​
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

StatusMeaningWhen it happens
200SuccessRequest completed successfully
400Bad RequestMalformed parameters — check filter values, missing required fields, or invalid formats
401UnauthorizedMissing or invalid API key
404Not FoundThe requested resource doesn’t exist (single-resource endpoints only)
429Too Many RequestsRate limit exceeded
500Server ErrorUnexpected 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"
    }
  ]
}
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)

​
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.

​
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, see Pricing to compare plans or upgrade in the Dashboard.

​
500 — Server Error

Returned when something unexpected goes wrong on Zerion’s side. 
{
  "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.

​
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.