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

# Errors & Rate Limits

> Every Analyst Consensus API error is one JSON object with a stable code — this page lists each code with its HTTP status and what to do, plus the rate-limit headers.

Every error is one JSON object: `error` (short legacy wording), `code` (stable — branch on this),
`message` (what happened and what to do), `docs_url`, and per code `param`, `required_plans` /
`upgrade_url` / `contact_url`, `limit` / `used` or `retry_after`.

```json theme={null}
{
  "error": "Premium or Enterprise plan required",
  "code": "PLAN_REQUIRED",
  "message": "This key (Free plan) has no access to per-analyst data. Per-analyst endpoints are available on the Premium and Enterprise plans: subscribe to CryptoQuant Premium (upgrade_url) or contact CryptoQuant for Enterprise / trial access (contact_url).",
  "docs_url": "https://docs.cryptoquant.com/sentiment/plans-and-access",
  "plan": "FREE",
  "required_plans": ["premium", "enterprise"],
  "upgrade_url": "https://cryptoquant.com/pricing",
  "contact_url": "https://cryptoquant.com/get-in-touch",
  "upgradeUrl": "https://cryptoquant.com/pricing"
}
```

<Note>
  These codes are specific to the Analyst Consensus API. The CryptoQuant Data API uses the
  `status`/`result` envelope described in [Status & Error Codes](/guides/status-codes).
</Note>

## Error codes

| `code` | HTTP | What to do |
| - | - | - |
| `API_KEY_REQUIRED` | 401 | Send the key in the `X-API-Key` header (or the `api_key` query parameter). The key-free endpoints (`/assets`, `/analysts/*`, `/analyst-views`, `/calls`, `/consensus` without `days`) need none. |
| `INVALID_API_KEY` | 401 | The key is unknown, inactive, expired, or its subscription is not active. Do not retry with the same key; obtain a valid one. |
| `PLAN_REQUIRED` | 401 | The key's plan cannot read this endpoint. `required_plans` names the plans that can: upgrade at `upgrade_url` or contact sales at `contact_url`. Do not retry on the same plan. |
| `RAW_ACCESS_REQUIRED` | 403 | The original source statement (full post text) is provided under an Integration agreement only, per key (not a plan: premium, enterprise and admin-owned keys without it get the excerpt). Drop `source_text=statement` to receive the ≤ 200-character excerpt + source link, or contact [sales@cryptoquant.com](mailto:sales@cryptoquant.com) (`contact_email`) for Integration raw-text access. Do not retry unchanged. |
| `DAILY_LIMIT_EXCEEDED` | 429 | Free plan daily quota used (`limit` / `used`). It resets at 00:00 UTC; wait, or upgrade. |
| `RATE_LIMIT_EXCEEDED` | 429 | Per-minute (keyed: your plan's `rate_limit_per_minute`; key-free: per-IP) limit hit. Wait `retry_after` seconds (header `Retry-After`), then retry; spread calls over the minute. |
| `INVALID_PARAMETER` | 400 | A query parameter is malformed or outside its accepted values: `param` names it and `message` lists what is accepted. Fix the request; never retry it unchanged. |
| `UNKNOWN_ASSET` | 400 | The asset is not registered. Resolve the name or ticker through [`GET /assets`](/sentiment/assets) (`symbol`, `key`, `name`, `aliases`) and retry with that symbol. |
| `ANALYST_NOT_FOUND` | 404 | No tracked analyst matches. Pick a handle from [`GET /analysts/top?asset=…`](/sentiment/top-analysts) (field `handle`) and retry. |
| `ANALYST_NOT_ELIGIBLE` | 404 | The analyst exists but is excluded from the stance pipeline (feed, company account, stakeholder). Not retryable. |
| `NO_DATA` | 404 | No rows for that analyst × asset pair in the queried range. Not retryable; try another asset the analyst covers (`covered_assets` on [`/analysts/{handle}`](/sentiment/analyst-track-record)). |
| `SERVICE_UNAVAILABLE` | 503 | An upstream list was unavailable. Retry after a few seconds with the same request. |
| `INTERNAL_ERROR` | 500 | Our fault. Retry once after a few seconds; if it persists, report the full URL to [support](https://cryptoquant.com/contact-us). |

## Rate limit headers

Responses include headers to help you track your usage:

| Header | Description |
| - | - |
| `X-RateLimit-Limit` | Requests allowed per minute (your plan's limit; per IP on the public endpoints) |
| `X-RateLimit-Remaining` | Requests remaining this minute |
| `Retry-After` | On a 429: seconds to wait before retrying (also `retry_after` in the body) |
| `X-Daily-Limit` | Daily limit (Free plan only) |
| `X-Daily-Used` | Requests used today (Free plan only) |

The per-plan limits are on [Plans & Access](/sentiment/plans-and-access).


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