Skip to main content

​
Errors

The API uses standard HTTP status codes and returns structured JSON error responses.

​
Error Response Format

{
  "error": "error_code",
  "message": "Human-readable description of what went wrong."
}

​
Status Codes

​
Success

CodeMeaning
200 OKRequest succeeded

​
Client Errors

CodeErrorDescription
400 Bad Requestvalidation_errorInvalid query parameters or request body. Check the message field for details.
401 Unauthorizedmissing_api_keyNo X-API-KEY header provided.
401 Unauthorizedinvalid_api_keyThe API key doesn’t match any active key.
401 Unauthorizedrevoked_api_keyThe key has been revoked. Generate a new one at Settings > API.
401 Unauthorizedexpired_api_keyThe key has expired. Generate a new one.
403 Forbiddenupgrade_requiredAPI access requires a Pro or Enterprise plan. Upgrade your account.
404 Not Foundnot_foundThe requested resource doesn’t exist. Check the ID or path.
422 Unprocessable Entityvalidation_errorRequest body or parameters failed validation.
429 Too Many Requestsrate_limit_exceededPer-minute rate limit exceeded. Check Retry-After header.
429 Too Many Requestsmonthly_quota_exceededMonthly API call quota exceeded. Resets on the 1st of each month.

​
Server Errors

CodeErrorDescription
500 Internal Server Errorinternal_errorSomething went wrong on our end. If this persists, contact support@vcm.fyi.
503 Service Unavailableservice_unavailableThe API is temporarily unavailable. Check the Retry-After header and try again later.

​
Handling Errors

​
Rate Limits (429)

When you receive a 429 response, the Retry-After header tells you how many seconds to wait: 
import time
import requests

response = requests.get(url, headers=headers)

if response.status_code == 429:
    retry_after = int(response.headers.get("Retry-After", 60))
    time.sleep(retry_after)
    response = requests.get(url, headers=headers)

​
Exponential Backoff

For production applications, implement exponential backoff: 
import time
import requests

def api_request(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)

        if response.status_code == 200:
            return response.json()

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

        response.raise_for_status()

    raise Exception("Max retries exceeded")