Error Handling

​

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)

​

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

​

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

​

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.