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)"
}

Retryable upstream failures include "retryable": true in the JSON body and a Retry-After: 60 response header. Provider authentication failures return 500 without those retry signals and should not be retried automatically.

Status codes

Authentication errors

Validation errors

These indicate invalid request data and don't count against your quota. Most are returned before a lookup; an upstream provider may also reject a structurally valid VIN. 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 lookup. 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

Insufficient prepaid credits (HTTP 402)

A prepaid account must have enough subscription and purchased credits combined to cover the full request. A positive balance can still be insufficient. Overage availability does not allow the wallet to go negative.

{
  "success": false,
  "code": "insufficient_credits",
  "message": "Insufficient credits. Add credits or enable auto-recharge to continue.",
  "billingUrl": "https://carsxe.com/dashboard/billing",
  "credits": { "available": 2, "cost": 5, "remaining": 0, "shortfall": 3 }
}

Open Billing to replenish credits. Plans that do not support credit purchases require an upgrade or assistance from support. remaining preserves the existing projected balance field; a rejected request does not spend the available credits.

If an authorized auto-recharge is still being processed, the API returns HTTP 503:

{
  "success": false,
  "code": "auto_recharge_pending",
  "message": "Auto-recharge is pending. Retry shortly after credits are confirmed."
}

Retry with backoff and the same idempotency key. Do not start a second payment because of this response. Successful API response formats are unchanged.

VIN ownership batches check the wallet before submission and charge the exact owner-record count before publishing each paid VIN result. If other requests consume the balance while the batch runs, affected VIN results contain code: "insufficient_credits", the credit shortfall, and no owner data. Top up and resubmit those VINs. Legacy postpaid billing remains unchanged.

Low-balance alerts

Prepaid accounts can configure a USD alert threshold in Billing → Credits (default $10). The value is an approximate top-up value of all remaining credits, not a cash balance. Eligible accounts receive dashboard warnings and one low-balance and one empty-balance email per depletion cycle. A balance above the configured threshold starts a new cycle. Healthy auto-recharge suppresses these warnings; failed auto-recharge does not.