Errors & Rate Limits - CryptoQuant API

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.

{
  "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"
}

These codes are specific to the Analyst Consensus API. The CryptoQuant Data API uses the status/result envelope described in Status & Error Codes.

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 (`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` (`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=…` (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}`).
`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.

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.