Rate limits and troubleshooting
This page covers the rate limiting behavior, HTTP status codes, and structured error codes returned by the CoinMarketCap Pro API. Use it to diagnose failed requests and to design retry logic.
API request throttling
Use of the CoinMarketCap API is subject to API call rate limiting or "request throttling". This is the number of HTTP calls that can be made simultaneously or within the same minute with your API key before receiving an HTTP 429 "Too Many Requests" throttling error. This limit scales with the usage tier and resets every 60 seconds. See Best practices for implementation strategies that work well with rate limiting.
HTTP status codes
The API uses standard HTTP status codes to indicate the success or failure of an API call.
| Status | Meaning | What to do |
|---|---|---|
400 Bad Request | The server could not process the request, likely due to an invalid argument. | Check query parameters and request body against the endpoint documentation. |
401 Unauthorized | Your request lacks valid authentication credentials. | Verify your API key is correct and included in the X-CMC_PRO_API_KEY header. |
402 Payment Required | Your paid subscription plan has an overdue balance. | Pay the balance in the Developer Portal billing tab. |
403 Forbidden | Your API key's service plan does not include this endpoint. | Check the plan-to-endpoint map and upgrade if needed. |
429 Too Many Requests | Rate limit exceeded. | Slow down request frequency (minute limit) or upgrade your plan (daily/monthly limit). |
500 Internal Server Error | An unexpected server issue was encountered. | Retry with exponential backoff. If persistent, check API status. |
Error response codes
A status object is always included in the JSON response payload for both successful calls and failures when possible. During error scenarios you may reference the error_code and error_message properties of the status object. One of the API error codes below will be returned if applicable, otherwise the HTTP status code for the general error type is returned.
| HTTP Status | Error Code | Error Message | Resolution |
|---|---|---|---|
| 401 | 1001 API_KEY_INVALID | This API Key is invalid. | Regenerate your key in the Developer Portal. |
| 401 | 1002 API_KEY_MISSING | API key missing. | Add the X-CMC_PRO_API_KEY header to your request. |
| 402 | 1003 API_KEY_PLAN_REQUIRES_PAYEMENT | Your API Key must be activated. | Activate your plan at pro.coinmarketcap.com/account/plan. |
| 402 | 1004 API_KEY_PLAN_PAYMENT_EXPIRED | Your API Key's subscription plan has expired. | Renew your subscription in the Developer Portal. |
| 403 | 1005 API_KEY_REQUIRED | An API Key is required for this call. | Include your API key — this endpoint is not available without one. |
| 403 | 1006 API_KEY_PLAN_NOT_AUTHORIZED | Your API Key subscription plan doesn't support this endpoint. | Upgrade your plan to access this endpoint. |
| 403 | 1007 API_KEY_DISABLED | This API Key has been disabled. | Contact support to resolve the issue. |
| 429 | 1008 API_KEY_PLAN_MINUTE_RATE_LIMIT_REACHED | You've exceeded your API Key's HTTP request rate limit. | Wait 60 seconds for the rate limit to reset, then retry. |
| 429 | 1009 API_KEY_PLAN_DAILY_RATE_LIMIT_REACHED | You've exceeded your API Key's daily rate limit. | Wait for the daily reset or upgrade your plan. |
| 429 | 1010 API_KEY_PLAN_MONTHLY_RATE_LIMIT_REACHED | You've exceeded your API Key's monthly rate limit. | Wait for the monthly reset or upgrade your plan. |
| 429 | 1011 IP_RATE_LIMIT_REACHED | You've hit an IP rate limit. | Reduce concurrent requests from this IP address. |