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

Code	Meaning
`200 OK`	Request succeeded

Client Errors

Code	Error	Description
`400 Bad Request`	`validation_error`	Invalid query parameters or request body. Check the `message` field for details.
`401 Unauthorized`	`missing_api_key`	No `X-API-KEY` header provided.
`401 Unauthorized`	`invalid_api_key`	The API key doesn’t match any active key.
`401 Unauthorized`	`revoked_api_key`	The key has been revoked. Generate a new one at Settings > API.
`401 Unauthorized`	`expired_api_key`	The key has expired. Generate a new one.
`403 Forbidden`	`upgrade_required`	API access requires a Pro or Enterprise plan. Upgrade your account.
`404 Not Found`	`not_found`	The requested resource doesn’t exist. Check the ID or path.
`422 Unprocessable Entity`	`validation_error`	Request body or parameters failed validation.
`429 Too Many Requests`	`rate_limit_exceeded`	Per-minute rate limit exceeded. Check `Retry-After` header.
`429 Too Many Requests`	`monthly_quota_exceeded`	Monthly API call quota exceeded. Resets on the 1st of each month.

Server Errors

Code	Error	Description
`500 Internal Server Error`	`internal_error`	Something went wrong on our end. If this persists, contact support@vcm.fyi.
`503 Service Unavailable`	`service_unavailable`	The 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")

​Errors

​Error Response Format

​Status Codes

​Success

​Client Errors

​Server Errors

​Handling Errors

​Rate Limits (429)

​Exponential Backoff