Errors and rate limits

Use the HTTP status and response body to decide whether to correct the request, check access, or retry. For API keys and authentication, see the shared quickstart.

Error bodies

REST error bodies use statusCode, message, and error. Validation errors can return an array of messages; authentication errors can return a string. Do not assume that every error has identical fields, especially when a gateway returns a non-JSON response. For example, an invalid asset_address on GET /v1/risk/token returns HTTP 400:

{
  "message": [
    "asset_address must be a valid Solana base58 address (32-44 chars, no 0 O I l)"
  ],
  "error": "Bad Request",
  "statusCode": 400
}

An invalid key on GET /v1/address returns HTTP 401:

{
  "message": "API key is invalid or not well-formed",
  "error": "Unauthorized",
  "statusCode": 401
}

Status codes

Status	How to handle it
`400 Bad Request`	Correct the parameters or body using the endpoint reference.
`401 Unauthorized`	Check the key, enabled API scopes, and authentication setup in the shared quickstart.
`403 Forbidden`	Check the workspace role and operation’s access requirements.
`404 Not Found`	Check the route and resource identifier. This is not a universal signal for an unsupported network.
`429 Too Many Requests`	Back off and retry with an increasing delay. If it keeps happening, check your credits.
`5xx`	Retry eligible reads with a bounded delay. Check Range status if failures persist.

Throttling

Reduce concurrent requests when you receive HTTP 429. For reads, use exponential backoff with jitter and a retry cap, for example three retries with increasing delays. Stop and investigate persistent failures rather than retrying indefinitely. Range API responses do not include rate-limit headers, such as X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, or Retry-After. Do not depend on response headers for a remaining request count, a reset time, or a retry delay. To see how many credits you have left, call Get workspace usage. Requests checked for limit headers on October 20, 2026:

API	Request checked	Observed limit headers
Data	`GET /v1/address` and `GET /v2/transfers`	None
Risk	`GET /v1/risk/payment`	None
Platform	`GET /v2/counterparties`	None

Retry boundaries

Correct validation and authentication failures before retrying.
Retry reads only when the operation’s behavior makes a repeat safe. Some screening reads also record workspace history.
After a timeout or server error on a create, update, or delete, check whether the change succeeded before repeating it. Do not apply a generic read retry loop to mutations.

Credits

Get workspace usage returns credit usage for the current billing period:

curl 'https://api.range.org/v1/workspace/usage' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Field	Meaning
`credits_used`	Credits consumed in the current billing period.
`credits_limit`	Credit limit reported for that period.
`credits_remaining`	Remaining credits, clamped at zero.
`reset_date`	Time the billing-period credit counter resets.

This reports credits, not your current request rate. If credits are exhausted, waiting between requests alone does not establish that access has been restored. Review usage and contact Range about your allocation.

Plan entitlements

Endpoint access depends on the modules activated for your account. Credit balance and request throttling do not establish that a module is enabled. See Plans and pricing and the key scopes.

Per-API notes

Data API

Validate network for the operation you call. An empty HTTP 200 result alone does not prove support for a network or activity for an address.

Risk API

Validation differs by operation. For example, Token Risk Assessment validates asset_address and requires network=solana; address screening must not be treated as an identical network-validation check. Use Test inputs for parsing and validation examples.

Platform API

Workspace membership and roles can restrict operations beyond API scope. Read the operation’s requirements before attempting changes.

MCP

MCP uses JSON-RPC, so inspect the protocol response as well as the HTTP status. A tool can return isError: true without a REST error body. For key types and the role required by mutating tools, see workspace access.

Introduction

Resources

Explorer Integrations

Errors and rate limits

Error bodies

Status codes

Throttling

Retry boundaries

Credits

Plan entitlements

Per-API notes

Data API

Risk API

Platform API

MCP

​Error bodies

​Status codes

​Throttling

​Retry boundaries

​Credits

​Plan entitlements

​Per-API notes

​Data API

​Risk API

​Platform API

​MCP

Error bodies

Status codes

Throttling

Retry boundaries

Credits

Plan entitlements

Per-API notes

Data API

Risk API

Platform API

MCP