This page is a complete reference for every error the CarsXE API can return. Each entry explains why the error happened and how to fix it, so you can resolve most issues without contacting support.

You can tell whether a request succeeded from the HTTP status code. Every response body also includes a success boolean, so you can check either one.

The error envelope

All errors share the same JSON shape:

{
  "success": false,
  "message": "Missing vin (vehicle identification number)"
}

Status codes

Authentication errors

Validation errors

These are returned before any lookup happens, so they don't count against your quota. Fix the request and resend.

The Recalls Batch endpoints have additional validation rules (VIN count, CSV size and hosting, webhook URLs) — those messages are self-describing and documented on the batch page.

Data not found

A 404 with one of these messages means the request was valid, but no data exists for that vehicle. Retrying the same input returns the same result.

Rate limit and quota errors

A 429 means you've used up your plan's included volume for this API:

{
"success": false,
"message": "API limit exceeded for market_value (6/2026). Subscription tier: starter. Current usage: 5000, Limit: 5000.",
"usage": {
  "current": 5000,
  "limit": 5000,
  "remaining": 0
}
}

See Rate Limits & Quotas for how limits work, the exact response shapes, and backoff strategies.

Server and upstream errors

CarsXE aggregates data from multiple providers. When a provider fails or times out, you'll see one of these:

Handling errors in code

Check response.ok / the status code first, then branch on the category. Retry only 5xx — a 4xx (including quota 429s, which persist until you upgrade or enable overage) needs a fix, not a retry:

CARSXE_API_KEY="CARSXE_API_KEY"
URL="https://api.carsxe.com/specs?key=${CARSXE_API_KEY}&vin=1HGCM82633A004352"
retries=3

for attempt in $(seq 0 $retries); do
  response=$(curl -s -w "\n%{http_code}" "$URL")
  body=$(echo "$response" | sed '$d')
  status=$(echo "$response" | tail -n 1)

  if [ "$(echo "$body" | jq -r '.success')" = "true" ]; then
    echo "$body"
    exit 0
  fi

  # 4xx: fix the request (or your quota) — retrying won't help
  if [ "$status" -lt 500 ]; then
    echo "CarsXE $status: $(echo "$body" | jq -r '.message')" >&2
    exit 1
  fi

  # 5xx: exponential backoff
  if [ "$attempt" -lt "$retries" ]; then
    sleep $((2 ** attempt))
  fi
done

echo "CarsXE request failed after retries" >&2
exit 1

CORS errors

The CarsXE API is meant to be called from your server, never from the browser. This protects your API key from being stolen — any key shipped to a browser is public. If you call the API from frontend JavaScript, the browser will block the request with a CORS error.

Route requests through your backend instead, and keep your key in an environment variable.

Still stuck?

If you've checked the tables above and the error doesn't make sense, contact support and include:

• The endpoint and parameters you sent (redact your API key)
• The full response body and HTTP status code
• The timestamp (with timezone) of the failing request