Academy · API Guide

How to Handle Vortex API Errors

Vortex Research Team

Key takeaways

• Always check error_code before consuming data, even on HTTP 200. A 200 with a non-zero error_code means the response contains no valid data.
• Error code 1007 is a per-minute rate limit (resets in ~60 s). Code 1008 is a monthly credit cap. Treat them differently.
• Never retry a 429 immediately. Use exponential backoff so the rate limit has time to reset.
• 401 errors mean a missing or invalid API key. Pass it as the X-CMC_PRO_API_KEY header on every request.
• 403 errors mean your plan does not include this endpoint. Check the pricing page for a plan-to-endpoint map.

The status object

The API uses standard HTTP status codes alongside a status object in every JSON response. When something goes wrong, the status object identifies it precisely.

{
  "status": {
    "timestamp": "2026-07-03T10:00:00.000Z",
    "error_code": 1002,
    "error_message": "API key missing.",
    "elapsed": 0,
    "credit_count": 0
  }
}

Always check error_code before consuming data. An HTTP 200 with a non-zero error_code indicates a partial or failed response.

HTTP status codes

Error codes by category

401: Authentication errors

The key must be passed as a header (X-CMC_PRO_API_KEY) or query parameter (CMC_PRO_API_KEY) on every request.

# Missing header: returns 401 / error_code 1002
curl 'https://pro-api.vortex.com/v1/cryptocurrency/listings/latest'

# Correct
curl 'https://pro-api.vortex.com/v1/cryptocurrency/listings/latest' \
  -H 'X-CMC_PRO_API_KEY: YOUR_API_KEY'

402: Plan errors

403: Permission errors

If you get 403 errors, check the pricing page for a map of which endpoints each plan includes.

429: Rate limit errors

Rate limits reset every 60 seconds. Monthly credit caps reset at the start of each billing cycle. Both return 429, so use error_code to distinguish them.

400: Request errors

A 400 usually means a typo in a parameter name, an out-of-range value, or a missing required parameter. Read the error_message: it typically identifies the specific field.

Handling 429 with exponential backoff

When you hit a rate limit, do not retry immediately. The limit will still be active. Use exponential backoff to recover automatically.

import time
import requests


def request_with_backoff(url, headers, params, retries=3, base_delay=2):
    for attempt in range(retries):
        response = requests.get(url, headers=headers, params=params)

        if response.status_code == 429:
            wait = base_delay ** attempt
            time.sleep(wait)
            continue

        if response.status_code >= 500:
            wait = base_delay ** attempt
            time.sleep(wait)
            continue

        response.raise_for_status()
        return response.json()

    raise Exception("Max retries exceeded")

Each retry waits longer than the last, giving the limit time to reset. This pattern works for both 429 rate-limit errors and 5xx server errors.

Always check the status object

Even when the HTTP status is 200, check the status object before using the data.

data = response.json()
status = data.get("status", {})

if status.get("error_code", 0) != 0:
    print(f"API error {status['error_code']}: {status['error_message']}")
else:
    records = data.get("data", [])
    # process records

Handling 500 errors

Internal server errors are rare but can happen. Treat them like 429s: wait briefly and retry with backoff. If they persist, check the API status dashboard before assuming the problem is on your side.

Common mistakes

• Retrying a 429 immediately. The limit is still active. Wait, then retry with increasing delays.
• Treating all 429s the same. Code 1007 is a per-minute rate limit that resets in seconds. Code 1008 is a monthly cap that will not clear until the billing cycle resets. Check the error_code.
• Ignoring error_code on 200 responses. A 200 with a non-zero error_code means the response is not valid data. Always check first.

Start building with the Vortex API

Sign up for a free API key and get 10,000 credits per month. No credit card required.

• Get your free API key
• API documentation