> For the complete documentation index, see [llms.txt](https://docs.nansen.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nansen.ai/getting-started/error-handling.md). # 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:**

Status Code	Meaning	What to Do
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: ```json { "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

{% hint style="info" %} 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. {% endhint %}
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.nansen.ai/getting-started/error-handling.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.