Docs · Errors & rate limits

API reference

Errors & rate limits

Errors return a JSON body with a stable error code and, where useful, a human-readable message.

Error shape

401 Unauthorized 
{
  "error": "invalid_api_key",
  "message": "That key is not valid. Check it, or create a new one in your dashboard."
}
402 Payment Required — sent when no key is supplied 
{
  "x402Version": 1,
  "accepts": [{
    "scheme": "exact",
    "network": "base",
    "maxAmountRequired": "10000",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0x…",
    "maxTimeoutSeconds": 60
  }],
  "error": "payment_required"
}
403 Forbidden 
{
  "error": "upgrade_required",
  "required_plan": "business",
  "message": "This endpoint requires the business plan or higher. See https://carvector.io/pricing."
}

Status codes

CodeMeaningWhen
200OKRequest succeeded.
401UnauthorizedInvalid or revoked API key. Error: invalid_api_key.
402Payment RequiredNo API key sent. The response carries x402 payment terms — pay per call, or send a key. Error: payment_required.
404Not FoundThe vehicle, code, or resource does not exist.
403ForbiddenYour plan tier does not include this endpoint. Error: upgrade_required.
429Too Many RequestsRate limit for your plan exceeded. See the Retry-After header.
503Service UnavailableData temporarily unavailable. Retry shortly.

Rate limits

Limits are enforced per plan across all of your keys, on a rolling window.

PlanRequests
Free500 per month
Developer10,000 per month
Pro100,000 per month
Business1,000,000 per month
EnterpriseCustom

Handling 429s

When you exceed your limit you'll get 429 with { "error": "rate_limit_exceeded", "limit": N, "window": "month" } and a Retry-After header (seconds). Back off for that many seconds, then retry — or move up a plan for more headroom.
← Endpoints Plans & pricing →