Error handling and status codes

​

Error response format

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

​

HTTP status codes

​

400 - Bad Request

{
  "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)
• An address Zerion doesn’t track (see below)

​

Untracked addresses

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

​

401 - Unauthorized

{
  "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

​

404 - Not Found

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

​

422 - Unprocessable Entity

{
  "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."
    }
  ]
}

​

429 - Too Many Requests

{
  "errors": [
    {
      "title": "Too many requests",
      "detail": "Your request had been throttled"
    }
  ]
}

​

500 - Server Error

{
  "errors": [
    {
      "title": "Internal Server Error",
      "detail": "An unexpected error occurred"
    }
  ]
}

​

503 - Service Unavailable

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

​

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.