How to Handle CoinMarketCap API Errors and Validation Responses

Find Your Code

The Response Envelope

Every response carries a status object, on success and on failure. It always includes the server time as timestamp, the credits consumed as credit_count, the processing time in milliseconds as elapsed, and on failure error_code and error_message.

{
  "status": {
    "timestamp": "2026-09-10T07:52:27.273Z",
    "error_code": 1002,
    "error_message": "API key missing.",
    "elapsed": 0,
    "credit_count": 0
  }
}

Two headers are expected on every request: Accept: application/json, and Accept-Encoding: deflate, gzip to keep responses compact.

The Type of error_code Depends on Which Endpoint You Call

This is the detail most likely to cost an afternoon. error_code arrives as a JSON number on some endpoints and a quoted string on others, and the boundary does not follow any rule you can apply from the outside.

Measured 10 September 2026 by reading the raw response text of each call and checking whether the value was quoted:

Twenty live observations against pro-api.coinmarketcap.com, 10 September 2026.

Three things make this harder to reason about than it first appears, each measured rather than assumed.

You can reproduce this in ten seconds without a key. Both calls below are unauthenticated, cost nothing, and return 1002:

# /v1 prints "error_code":1002 , a number
curl -s "https://pro-api.coinmarketcap.com/v1/cryptocurrency/quotes/latest?slug=bitcoin" | grep -o '"error_code":[^,]*'

# /v3 prints "error_code":"1002" , a string
curl -s "https://pro-api.coinmarketcap.com/v3/cryptocurrency/quotes/latest?slug=bitcoin" | grep -o '"error_code":[^,]*'

The first prints "error_code":1002 and the second prints "error_code":"1002". Same code, same second, same parameter, different JSON type. The /v1 envelope also carries a notice field that the /v3 envelope omits. If you take nothing else from this section, run those two commands against whichever endpoints your own code touches before you write a comparison against an integer.

The keyless prefix does not decide it. Calling an endpoint through /public-api returns the same type as calling it directly. /public-api/v2/cryptocurrency/ohlcv/historical returns a number; /public-api/v3/cryptocurrency/quotes/latest returns a string. The type belongs to the endpoint, not to the surface you reach it through.

Sending a key does not decide it either. A keyed request to /v4/cmc-ai/coins/latest on an expired subscription returns "1004" as a string, with a valid key present on the request.

The version number is not a reliable proxy. Most /v1 endpoints return a number, but /v1/simple/price and the whole /v1/dex/* family return strings. The split tracks which service handles the endpoint, which is not something a client can see.

The practical conclusion is not to memorise the table. It is that no strict equality check against a numeric literal is safe anywhere, so normalise once at the point of parsing and stop thinking about it.

def error_code(payload):
    raw = payload.get("status", {}).get("error_code", 0)
    try:
        return int(raw)
    except (TypeError, ValueError):
        return -1          # unparseable: treat as an unknown failure

Parse defensively more generally. Read only the fields you need, so new properties added later are ignored rather than breaking a parser, and wrap type-sensitive parsing such as dates in error handling. Keyed error responses, for instance, carry a notice field alongside the five documented keys.

HTTP Status Codes

Full Error Code Reference

Observed records a code confirmed by a live request on 10 or 14 September 2026. Documented records a code taken from the errors and rate limits guide: the four rate-limit codes are untested by design, since exercising them means deliberately exhausting a plan.

The Four 429s Are Not Interchangeable

One status code covers limits whose reset windows range from a minute to a month.

• 1008Clears in 60s

  The per-minute request rate. A short backoff recovers automatically.

• 1009Clears at daily reset

  Credit exhaustion for the day. No amount of backoff clears it.

• 1010Clears next period

  Credit exhaustion for the month. The billing cycle has to roll over, or the plan has to change.

• 1011Clears on lower concurrency

  An IP-level limit rather than a key-level one, which usually means several workers sharing one address.

A retry loop that treats all four alike will hammer a monthly cap every few seconds until the billing cycle turns over.

import time
import requests

TRANSIENT = {1008, 1011}                                  # backoff clears these
EXHAUSTED = {1009, 1010}                                  # only a reset or upgrade clears these
FATAL = {1001, 1002, 1003, 1004, 1005, 1006, 1007, 400, 4001, 4002}

def call(url, headers, params, retries=4, base_delay=1):
    for attempt in range(retries):
        r = requests.get(url, headers=headers, params=params)
        code = error_code(r.json())                       # normalised, see above

        if code in FATAL:
            raise RuntimeError(f"Not retryable: {code}")
        if code in EXHAUSTED:
            raise RuntimeError(f"Allowance exhausted: {code}")
        if code in TRANSIENT or r.status_code >= 500:
            time.sleep(base_delay * (2 ** attempt))
            continue
        if code:
            raise RuntimeError(f"API error {code}")

        return r.json()

    raise RuntimeError("Max retries exceeded")

The separation matters more than the delays. Backoff belongs to 1008 and 1011; everything else needs a decision rather than a wait.

Errors a Retry Cannot Fix

Three codes look transient and are not. 1006 means the plan does not cover the endpoint, so the request will fail identically until the plan changes. 1007 means the key has been disabled, which support has to resolve. 1005 means the endpoint requires authentication and the request arrived without a key, which is configuration rather than permission.

Code 4001 on the CMC AI Endpoints

The /v5/cmc-ai family introduces one additional code. On /v5/cmc-ai/coins/latest, which accepts comma-separated lists of crypto_id, slug or symbol, an identifier that cannot be resolved fails the whole request with 4001 by default.

That default is worth changing for most batch work. Passing skip_invalid=true drops the unresolvable identifiers and returns the valid ones, so one bad symbol in a list of fifty does not cost the other forty-nine. Coins skipped this way are not charged.

# One bad identifier fails everything (skip_invalid defaults to false)
GET /v5/cmc-ai/coins/latest?symbol=BTC,ETH,ZZZNOTREAL

# Same request, partial results instead of a failure
GET /v5/cmc-ai/coins/latest?symbol=BTC,ETH,ZZZNOTREAL&skip_invalid=true

The same endpoint enforces mutual exclusivity: exactly one of crypto_id, slug or symbol is required, and supplying two is a request error rather than a silent preference for one.

Behaviour Worth Knowing Before You Debug

Validation already exists on the current endpoints, and three of its behaviours surprise people.

Live requests to the keyless endpoints, executed 10 September 2026.

The last two are the ones to code around.

A nonexistent symbol returns success. Nothing in the envelope reports that the asset you asked for is missing, so check that the response actually contains each identifier you requested. This is the strongest argument for using CoinMarketCap IDs from /cryptocurrency/map: a symbol matching several cryptocurrencies resolves silently to the highest market cap, a symbol matching none returns silently empty, and neither surfaces as an error.

A mistyped path returns HTTP 200 with a “system is busy” message. That reads like a transient outage and is not one, so a client that retries on it will retry forever against a URL that will never exist. Check the path against the endpoint reference before assuming the service is degraded.

Common Mistakes

• Retrying every 429.

  Four limits share that status. 1008 clears in a minute; 1010 does not clear this month.

• Ignoring error_code on a 200.

  A 200 with a non-zero code carries no data. Check the code first, always.

• Comparing error_code to a numeric literal.

  It is a number on the older /v1 and /v2 endpoints and a string on /v3, DEX, CMC AI and keyless. Normalise once at parse time.

• Backing off on a 403.

  1006 and 1007 are plan and key states, and will return the same answer indefinitely.

• Retrying “the system is busy”.

  On an unknown path that message arrives with HTTP 200 and will never clear. Verify the path first.

• Assuming a missing asset produces an error.

  A nonexistent symbol returns 200 with error_code "0".

A 500 Is Not Always Transient

The status table says to retry a 500 with exponential backoff, and that is right for a genuine server blip. It is not always what a 500 means here. Two behaviours observed on 11 September 2026 break the assumption.

An unrecognised path returns HTTP 200 with error_code "500" and “The system is busy, please try again later!”. A typo in a path segment therefore reads to a client as a successful call reporting a transient fault. /v9/cmc-ai/latest returns a clean 404, so version routing is correct and sub-path routing is not.

At least one real endpoint returns a persistent 500. /v1/dex/holders/trend/list returned HTTP 500 with the same “system is busy” message both without parameters and with valid ones, while its sibling endpoints answered normally in the same pass.

In both cases a correct retry-with-backoff implementation retries forever. So cap your retries on 500 rather than looping indefinitely, and treat a 500 that survives a few attempts as a permanent failure to surface, not a transient one to keep hammering. Log the full path when you do: the most likely cause is that the URL is wrong rather than the server being busy.

Two Codes the Documentation Does Not List

The published error table runs 1001 to 1011. Two more codes are returned live and appear in no error reference.

4001 is documented, but only in passing: it appears in the skip_invalid parameter description on /v5/cmc-ai/coins/latest, not in the error table. It means an identifier could not be resolved.

4002 appears nowhere at all. Its message is “Missing required parameter.”, and it was confirmed by controlled test on 11 September 2026: /v1/dex/holders/count and /v1/dex/holders/tag_count both declare platform and tokenAddress as required. Omitting either returned HTTP 400 with error_code 4002. Supplying both returned HTTP 200. Every other endpoint tested in the same pass declares no required parameter and returned a plain 400 instead, with a different message.

So 4002 means a required parameter is missing, and it is raised by a different validation layer from the generic 400. Both are permanent failures: no retry fixes either, and neither is charged.

That distinction is useful in a handler. A 400 may mean your value was wrong; a 4002 means a parameter was absent entirely, which is a different fix and usually a coding error rather than a data error.

FAQ