# Errors

> Crius API error format, HTTP status codes and every error code with its meaning and what to do about it.

Source: https://docs.crius.sh/errors/ · Updated 2026-10-28

Errors return a non-2xx HTTP status and a JSON body:

```json
{
  "error": {
    "code": "plan_required",
    "message": "This endpoint needs an API key (Free plan or higher); you called it without one. To use it, get a free API key at https://dashboard.crius.sh.",
    "plan": "anon",
    "required_plan": "free",
    "upgrade_url": "https://dashboard.crius.sh",
    "docs_url": "https://docs.crius.sh/plans-and-limits/"
  }
}
```

Match on `error.code` (stable, machine-readable); `message` is for humans and may change. Plan and limit errors also carry the fields shown here (see [Plans & limits](https://docs.crius.sh/plans-and-limits/#rate-limit-headers)).

## Authentication and access

| Status | Code | Meaning | What to do |
| --- | --- | --- | --- |
| 401 | `key_required` | This endpoint needs a key and none was sent | Send `x-api-key` |
| 401 | `invalid_key` | The key doesn’t exist or the secret is wrong | Check for typos or a truncated key |
| 401 | `key_rotated` | The key was rotated and its grace period ended | Use the new key |
| 401 | `key_revoked` | The key was revoked | Create a new key |
| 401 | `key_expired` | The key passed its expiry date | Create a new key |
| 403 | `account_suspended` | The account is suspended | Contact [support@crius.sh](mailto:support@crius.sh) |
| 403 | `plan_required` | Your plan doesn’t include this endpoint (`required_plan` says which does) | Get a key or upgrade at `upgrade_url`, see [plans](https://docs.crius.sh/plans-and-limits/) |
| 403 | `scope_required` | The key lacks the scope (`stream`, `simulate`) | Edit the key’s scopes |
| 403 | `ip_not_allowed` | The client IP isn’t in the key’s allow-list | Update the allow-list |
| 403 | `origin_not_allowed` | The browser origin isn’t allowed for this key | Add the origin to the key |
| 403 | `session_required` | Account management needs a dashboard session | Use the dashboard |
| 403 | `session_not_api_key` | A dashboard session was used on a data endpoint | Use an API key |

## Limits

| Status | Code | Meaning | What to do |
| --- | --- | --- | --- |
| 429 | `rate_limited` | Over your requests-per-second limit (the body has `limit_rps`, `burst`, `retry_after_ms`) | Wait `retry-after` seconds, then retry; or use a key / bigger plan (`upgrade_url`) |
| 429 | `quota_exceeded` | Monthly credits used up (the body has `monthly_credits` and `resets`) | Upgrade (`upgrade_url`) or wait for the reset date |
| 429 | `auth_banned` | Too many failed authentications from this IP | Wait 60 s and fix the key |
| 503 | `busy` | Too many heavy analytics requests in flight | Retry shortly with backoff |

## Requests

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `invalid_address` | Not a valid `0x` address |
| 400 | `invalid_pool` | Not a valid pool address or v4 pool id |
| 400 | `invalid_interval` | Unsupported candle interval |
| 400 | `invalid_window` | Unsupported stats window |
| 400 | `invalid_cursor` | The cursor is malformed or from another list |
| 400 | `invalid_at` | The point in time (`at`, `from`, `to`) couldn’t be parsed |
| 400 | `invalid_list`, `invalid_sort`, `invalid_tz` | An unsupported option |
| 400 | `too_many_tokens` | More than 100 tokens in a batch |
| 400 | `window_too_large` | The requested time window is too large for this endpoint |
| 400 | `token_too_active` | The token has too much history for this query (holder history) |
| 400 | `invalid_request` | Malformed query string or body |
| 413 | `payload_too_large` | Request body over 256 KB |

## Not found

| Status | Code | Meaning |
| --- | --- | --- |
| 404 | `chain_not_found` | Unknown chain slug or id |
| 404 | `token_not_found` | We have no token at this address |
| 404 | `pool_not_found` | No such pool |
| 404 | `wallet_not_found`, `dev_not_found` | No activity for this address |
| 404 | `hook_not_found`, `launch_not_found`, `launchpad_not_found` | No such hook, launch or launchpad |
| 404 | `point_not_found` | The point in time (`mcap:`, `graduation`…) never happened for this token |
| 404 | `not_ready` | The data is still being indexed; retry shortly |
| 404 | `stream_unavailable` | The stream isn’t enabled on this node |

## Server

| Status | Code | Meaning |
| --- | --- | --- |
| 500 | `internal` | Something broke on our side; it is logged. Retry, and contact support if it persists |
| 504 | `timeout` | The request took longer than 10 seconds |

Check [status.crius.sh](https://status.crius.sh) for ongoing incidents.