🟢Understanding Responses and Handling Errors

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	Description
200 OK	The request was successful, and the response body contains the requested data.
400 Bad Request	The request was malformed (e.g., invalid parameters, incorrect format). Check the request syntax and parameters.
401 Unauthorized	Authentication failed. The access token is missing, invalid, or expired. Obtain/refresh the token.
403 Forbidden	Authentication succeeded, but the user does not have permission to access the requested resource
404 Not Found	The requested resource (e.g., specific address, endpoint path) does not exist.
429 Too Many Requests	The client has exceeded the allocated rate limit.
500 Internal Server Error	An unexpected error occurred on Nansen's servers.
504 Gateway Timeout	API didn't get a timely response from backend server

Latency Expectations & Best Practices

As we continue to improve the performance of the Nansen API, here are some general guidelines to help you understand what to expect and how to get the best results:

What to Expect

• Most core endpoints (e.g. smart money, profiler) typically respond in under 2 seconds.

• Some heavier endpoints (especially under the TGM namespace) may take longer depending on the scope of the query.

• We’re actively working towards improving the performance of the API

Best Practices for Low Latency

To get faster and more reliable responses:

• Avoid overly broad queries. For example, don’t request balances for every address holding USDC across the entire chain.

• Use filters when available to narrow down time ranges, token lists, or entity types.

• Paginate where supported instead of trying to fetch large datasets in one go.

• Be mindful of rate limits, especially if calling multiple endpoints in parallel.