Error Handling

All REST API errors return a JSON body with a consistent structure. WebSocket errors are covered separately in WebSocket Error Codes.

Response Format

Every error response includes at minimum a detail field and the request path:

{
  "detail": "Snapshot not found",
  "path": "/atlas/v1/sol/EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v/snapshots/0"
}

Validation errors (422) include additional context:

{
  "detail": [
    {
      "loc": ["path", "network"],
      "msg": "value is not a valid enumeration member",
      "type": "value_error.enum"
    }
  ],
  "body": null,
  "path": "/scanner/v1/tokens/invalid/0x..."
}

HTTP Status Codes

Status	Meaning	When
200	OK	Request succeeded
400	Bad Request	Invalid input that doesn't match a validation schema (e.g. too many addresses in Labels API)
401	Unauthorized	Missing, malformed, or inactive API key
404	Not Found	Resource does not exist (e.g. snapshot not found for this token/timestamp)
422	Unprocessable Entity	Request is structurally valid but contains invalid values (e.g. unknown network, bad address format)
429	Too Many Requests	Rate limit exceeded -- see Authentication for details on rate limiting
500	Internal Server Error	Unexpected server error. The response body contains `"detail": "Internal server error."`
501	Not Implemented	Endpoint exists but is not yet available for the requested network or feature

Handling Errors

Check the Status Code First

response = requests.get(url, headers={"X-API-Key": key})

if response.status_code == 200:
    data = response.json()
elif response.status_code == 401:
    print("Invalid API key")
elif response.status_code == 404:
    print("Resource not found")
elif response.status_code == 429:
    retry_after = response.headers.get("Retry-After", "60")
    print(f"Rate limited. Retry in {retry_after}s")
elif response.status_code == 422:
    errors = response.json().get("detail", [])
    for err in errors:
        print(f"Validation error: {err}")
else:
    print(f"Unexpected error: {response.status_code}")

Retry Strategy

Status	Retry?	Strategy
401	No	Fix your API key
404	No	The resource doesn't exist
422	No	Fix the request parameters
429	Yes	Wait for `Retry-After` seconds, then retry
500	Yes	Retry with exponential backoff (e.g. 1s, 2s, 4s, 8s)
501	No	Feature not yet available for this network

Cached Responses

Some endpoints cache results for performance. When a response is served from cache, the header X-Cached-Response: true is present. Cached responses have the same structure as fresh responses.