Error Handling

API responses are delivered in JSON format. The client applications must parse this JSON to extract the required data. Equally important is handling the HTTP status code returned with each response to determine success or failure.

Common HTTP Status Codes:

400	Bad Request: Malformed request, invalid parameters or format	Check your request syntax and parameters
401	Unauthorized: Authentication failed (missing, invalid, or expired token)	Obtain or refresh your API Key
402	x402: Payment Required	Please make the payment for API request and try again
403	Forbidden: Auth succeeded, but no permission for resource	Ensure your account has access rights
404	Not Found: Resource or endpoint does not exist	Verify the endpoint path and resource identifiers
422	Unprocessable Content	Please verify your parameters
429	Too Many Requests: Rate limit exceeded	Slow down requests; respect rate limits
500	Internal Server Error: Unexpected server issue	Try again later; contact support if persistent
504	Gateway Timeout: Backend server did not respond in time	Retry after a short wait; check for heavy queries

Error Codes

Except for HTTP 402 payment challenges, error responses carry a structured JSON body with a stable, machine-readable code field:

{
  "error": "Missing field",
  "message": "Required field 'body -> chain' is missing. Must be a valid chain name, e.g., 'ethereum', 'solana', 'bnb'",
  "code": "missing_field",
  "status": 422,
  "request_id": "req-6b1f6f3f2b724e4bb8b2f6d0a9e4c1aa",
  "doc_url": "https://docs.nansen.ai/getting-started/error-handling#missing_field",
  "param": "chain"
}

• code — a stable identifier for the error; safe to branch on in client code.

• status — the HTTP status code, repeated in the body.

• request_id — include this when contacting support.

• doc_url — links back to this page, anchored to the specific code.

• param — only present when the error relates to a specific request field.

• retry_after — only present when the request can be retried after a delay, in seconds. The same value is sent in the Retry-After response header.

All error codes:

Code	Meaning	Typical cause	Retryable
missing_field	A required field is missing from the request	A required body field (e.g. chain, date) was not provided	No — add the field
unknown_field	The request contains a field the endpoint does not recognize	A typo, a camelCase name (the API uses snake_case), or page/per_page outside the pagination object	No — fix the field name
invalid_field_value	A field value is invalid for this endpoint	Wrong type, or a value outside the allowed options (e.g. an unsupported chain name)	No — fix the value
invalid_address_format	A wallet or token address is not valid for the specified chain	Missing 0x prefix, wrong length, non-hex characters, or an address from a different chain	No — fix the address
invalid_date_format	A date is not in the expected format	Dates must be {"from": "YYYY-MM-DD", "to": "YYYY-MM-DD"}	No — fix the date format
invalid_date_range	The requested date range is not allowed	Range longer than one year, or beyond the per-address limit for high-volume addresses	No — narrow the range
mutually_exclusive_fields	Two fields that cannot be combined were both provided	Sending both of a pair of alternative parameters in the same request	No — remove one of the fields
value_out_of_range	A value is outside the allowed bounds	A number above or below the documented limit, or a string that is too short or too long	No — adjust the value
too_many_items	A list contains more items than allowed	More entries than the field's maximum length	No — split into smaller batches
unauthenticated	Authentication failed	Missing, invalid, or expired API key	No — obtain or refresh your API key
forbidden	Authenticated, but no permission for this resource	Your account lacks access rights for the endpoint or data	No — check your account's access
geo_blocked	Access is blocked in your region	Request originates from a restricted jurisdiction	No
plan_upgrade_required	The feature requires a higher subscription plan	Using a paid feature (e.g. premium_labels=true) on a Free plan	No — upgrade your plan
insufficient_credits	Not enough API credits remain to call this endpoint	Credit balance is below the endpoint's credit cost	No — add credits or upgrade your plan
rate_limit_exceeded	Too many requests	Request rate above your plan's rate limit	Yes — wait Retry-After seconds, then retry
not_found	The endpoint or resource does not exist, or is no longer available	Wrong endpoint path or resource identifier	No — verify the path
method_not_allowed	The HTTP method is not allowed for this endpoint	Using GET on a POST-only endpoint	No — use the documented method
conflict	The request conflicts with the current state	A duplicate or contradictory operation	No — check your data
payload_too_large	The request body is too large	Payload exceeds the size limit	No — reduce the payload
query_timeout	The query took too long to complete	A very wide date range or an expensive, unfiltered query	Yes — retry with backoff; wait Retry-After seconds when present; consider narrowing the query
query_too_large	The query exceeds system limits	The time range or parameter set would produce too much data	No — reduce the time range or add filters
upstream_unavailable	An upstream service is temporarily unavailable	Maintenance or overload of a backend service	Yes — retry with backoff; wait Retry-After seconds when present
internal_error	Unexpected server-side error	A fault on our side, not your request	Yes — retry with backoff; contact support with your request_id if it persists

The set of error codes may expand over time. Clients must tolerate unknown codes: when you receive a code you don't recognize, fall back to handling the response by its HTTP status.