Errors

When a request cannot be completed, the API responds with a non-2xx HTTP status code and a JSON body describing what went wrong. Every error body shares the same envelope, so you can handle failures with a single code path.

Error response shape

HTTP/1.1 404 Not Found
{
  "status": "fail",
  "type": "COIN_NOT_FOUND",
  "message": "Coin not found"
}

Field	Type	Description
`status`	String	`fail` for `4xx` client errors, `error` for `5xx` server errors.
`type` / `code`	String	A stable, machine-readable identifier for the error. Branch on this rather than on `message`. See the note below on which field is present.
`message`	String	A human-readable explanation. This text may change over time, so do not match on it programmatically.

`type` vs `code`: Errors raised by the API itself (a coin that does not exist, an invalid parameter, a bad cursor) carry a type field. Errors raised by the gateway in front of the API (authentication, plan access, and rate limiting) carry a code field instead. Both always include status and message. If you read the identifier defensively — for example body.type || body.code — you will handle either family.

HTTP status codes

Status	Meaning
`200`	Success.
`401`	Unauthorized — the API key is missing or invalid.
`403`	Forbidden — your plan does not include this endpoint.
`404`	Not found — the requested resource (or route) does not exist.
`410`	Gone — the endpoint has been removed.
`422`	Unprocessable entity — a parameter failed validation.
`429`	Too many requests — you have hit a rate limit.
`5xx`	A server-side or upstream error. `status` is `error`. Retry with backoff.

API errors

These are returned by the API and carry a type field.

Type	Status	When it happens
`VALIDATION_ERROR`	422	A query or path parameter failed validation. The `message` names the offending parameter.
`COIN_NOT_FOUND`	404	No coin matches the requested UUID.
`EXCHANGE_NOT_FOUND`	404	No exchange matches the requested UUID.
`MARKET_NOT_FOUND`	404	No market matches the requested UUID.
`PRICE_NOT_FOUND`	404	No price is available for the requested resource.
`BLOCKCHAIN_NOT_FOUND`	404	The blockchain is not recognised. See `/v2/blockchains` for valid values.
`GAINS_AND_LOSSES_NOT_FOUND`	404	No gains-and-losses data is available for the request.
`INVALID_TIMEPERIOD_REFERENCE_COMBINATION`	404	No change could be calculated for this reference currency in this time period (the reference currency likely did not exist yet).
`TOO_MANY_REQUESTS`	429	A per-endpoint fair-use limit was hit — for example the daily quota on deep historical OHLCV requests. Distinct from the gateway's `RATE_LIMIT_EXCEEDED`. Slow down and retry.
`REFERENCE_UNAVAILABLE`	422	The `referenceCurrencyUuid` is not a valid reference currency. See the reference currencies endpoint.
`TAG_UNAVAILABLE`	422	The requested `tag` is not available.
`PAGE_UNAVAILABLE`	422	The requested page slug is not available.
`INVALID_CURSOR`	422	The `cursor` is malformed or could not be decoded. Start pagination from the beginning.
`CURSOR_MISMATCH`	422	The `cursor` was created with a different `orderBy`/`orderDirection`. Match the original parameters or start over.
`PAGINATION_CONFLICT`	422	Both `cursor` and `offset` were supplied. Use only one pagination method per request.
`OFFSET_TOO_LARGE`	422	The `offset` exceeds the maximum of 5000. Use cursor-based pagination for deeper results.
`UNKNOWN_ERROR`	500	An unexpected server error. `status` is `error`. Retry with backoff and contact support if it persists.

For more on the pagination errors, see the pagination guide.

Access & rate-limit errors

These are returned by the gateway and carry a code field.

Code	Status	When it happens
`UNAUTHORIZED`	401	The API key is missing or invalid. See authentication.
`FORBIDDEN`	403	Your subscription plan does not include this endpoint. Upgrade your plan.
`RATE_LIMIT_EXCEEDED`	429	You have reached a rate limit for your plan. See rate limits.
`PREVIEW_LIMIT_REACHED`	429	Your account has used this endpoint's daily successful preview allowance. Wait until 00:00 UTC or upgrade for production access. See endpoint previews.
`PREVIEW_CAPACITY_BUSY`	503	Requests in progress have reserved the available preview slots. Retry after the `Retry-After` delay.
`PREVIEW_UNAVAILABLE`	503	Preview access is temporarily unavailable. Retry with backoff.
`NOT_FOUND`	404	The requested route does not exist. Check the path against the documentation.
`ENDPOINT_NOT_SUPPORTED`	410	The endpoint has been removed. Use the latest documentation.
`BAD_GATEWAY`	502	The upstream service was unavailable. Retry with backoff.
`GATEWAY_TIMEOUT`	504	The upstream service timed out. Retry with backoff.

Rate-limit exceeded

When you exceed a rate limit, the gateway returns 429 with a RATE_LIMIT_EXCEEDED body:

HTTP/1.1 429 Too Many Requests
{
  "status": "fail",
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "You've reached the API request limit. Please upgrade your subscription plan: https://coinranking.com/api/pricing"
}

If the request was made without an API key, the message instead points you to create a free key. Every response — including this one — carries rate-limit headers, and 429 responses add a retry-after header telling you how many seconds to wait before retrying. See the rate limits page for the full list of headers.

Handling errors

Branch on the identifier, not the message. The type/code values are stable; message text is not, and may change without notice.

Retry 429 and 5xx responses with exponential backoff. Honour the retry-after header on 429 responses. Do not retry 4xx errors other than 429 — they will keep failing until you change the request.