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 — a rate limit or credit exhaustion. Rate limits recover after a short wait; `credits_exhausted` requires adding credits or waiting for your allowance reset. Check the response `code`.
`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.
`credits_exhausted`	429	Not enough available credits to admit the request. Add credits or wait for your allowance reset. See credit exhaustion.
`credit_migration_in_progress`	503	Your account is temporarily paused while its credit migration completes. Retry with backoff.
`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. Rate-limit responses carry rate-limit headers and a retry-after header telling you how many seconds to wait before retrying. A 429 with code: "credits_exhausted" instead requires available credits; a short retry delay will not replenish your balance. 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 short-term rate limits and 5xx responses with exponential backoff. Honour the retry-after header for short-term rate limits. Do not automatically retry credits_exhausted, even though it returns 429: add credits or wait for your allowance reset before trying again. Other 4xx errors require correcting the request or meeting the stated access conditions.