> ## Documentation Index
> Fetch the complete documentation index at: https://docs.range.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors and rate limits

> Handle Range API errors, retry throttled requests, and distinguish request limits, credits, and plan access.

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](https://docs.range.org/introduction/quickstart.md).

## 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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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](#credits). |
| `5xx` | Retry eligible reads with a bounded delay. Check [Range status](https://status.range.org) 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](#credits).

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](https://docs.range.org/platform-api/api-reference-introduction.md) returns credit usage for the current billing period:

```bash theme={null}
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](https://www.range.org/contact) 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](https://docs.range.org/introduction/plans-and-pricing.md) and the [key scopes](https://docs.range.org/introduction/quickstart.md#api-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](https://docs.range.org/risk-api/risk/get-token-risk-assessment.md) validates `asset_address` and requires `network=solana`; address screening must not be treated as an identical network-validation check. Use [Test inputs](https://docs.range.org/resources/test-inputs.md#risk-api) 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](https://docs.range.org/introduction/quickstart.md#key-types-and-workspace-access).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.