> ## Documentation Index
> Fetch the complete documentation index at: https://docs.api.vcm.fyi/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> HTTP status codes and error response format

# Errors

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

## Error Response Format

```json theme={null}
{
  "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](https://app.vcm.fyi/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](https://app.vcm.fyi/settings). |
| `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](mailto: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:

```python theme={null}
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:

```python theme={null}
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")
```