Errors

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 envelopeCopiar seção para LLMCopiar link para a seçãoPerguntar à IA sobre esta seção

All errors share the same JSON shape:

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

Status codesCopiar seção para LLMCopiar link para a seçãoPerguntar à IA sobre esta seção

Authentication errorsCopiar seção para LLMCopiar link para a seçãoPerguntar à IA sobre esta seção

Validation errorsCopiar seção para LLMCopiar link para a seçãoPerguntar à IA sobre esta seção

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 foundCopiar seção para LLMCopiar link para a seçãoPerguntar à IA sobre esta seção

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 errorsCopiar seção para LLMCopiar link para a seçãoPerguntar à IA sobre esta seção

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 errorsCopiar seção para LLMCopiar link para a seçãoPerguntar à IA sobre esta seção

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

Handling errors in codeCopiar seção para LLMCopiar link para a seçãoPerguntar à IA sobre esta seção

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 errorsCopiar seção para LLMCopiar link para a seçãoPerguntar à IA sobre esta seção

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?Copiar seção para LLMCopiar link para a seçãoPerguntar à IA sobre esta seção

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