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": "missing_api_key",
  "message": "Send your key as: Authorization: Bearer cv_…"
}

403 Forbidden

{
  "error": "upgrade_required",
  "required_plan": "business",
  "message": "This endpoint requires the business plan or higher. See https://carvector.io/pricing."
}

Status codes

Code	Meaning	When
`200`	OK	Request succeeded.
`401`	Unauthorized	Missing or invalid API key. Errors: missing_api_key, invalid_api_key.
`404`	Not Found	The vehicle, code, or resource does not exist.
`403`	Forbidden	Your plan tier does not include this endpoint. Error: upgrade_required.
`429`	Too Many Requests	Rate limit for your plan exceeded. See the Retry-After header.
`503`	Service Unavailable	Data temporarily unavailable. Retry shortly.

Rate limits

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

Plan	Requests
Free	500 per month
Developer	10,000 per month
Pro	100,000 per month
Business	1,000,000 per month
Enterprise	Custom

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 →