CarsXECarsXE

CarsXE limits are volume-based quotas tied to your subscription, not per-second throttles. Each API has an included monthly volume for your tier; when you reach it, what happens next depends on your overage settings. This page explains how the quotas work, exactly what a 429 looks like, and how to handle limits gracefully in code.

There are no per-second request throttles on standard plans, but keep burst concurrency reasonable — extremely aggressive parallel traffic can still be rejected upstream before it reaches your quota.

How quotas work

You can see your current usage per API at any time on the developer dashboard.

What happens when you hit the limit

There are two possible behaviors, controlled by your overage billing preference in the dashboard:

Overage billingBehavior past the included quota
Enabled (default on plans with overage pricing)Requests keep succeeding. Each unit past your included volume is billed at your tier's per-call overage rate. You will never see a quota 429.
Disabled (opt-out)Requests are rejected with a 429 until the period resets or you re-enable overage.

Enterprise plans use custom pricing and monthly invoicing — included volume and overage terms are set in your contract.

The 429 response

Quota errors use the standard error envelope plus a usage object:

json
{
"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
}
}

The message tells you which API hit its limit, the billing period (month/year), your tier, and the exact numbers. Variants you may see:

Credit-wallet accounts

Accounts billed from a credit wallet don't have per-API monthly quotas, so they never see a quota 429. Each call deducts credits from the wallet instead, and the two failure modes below replace it.

StatusWhenRetry?
402The wallet doesn't hold enough credits for this request.No — add credits or enable auto-recharge first.
503Billing couldn't be verified: an auto-recharge is still settling, or a transient backend problem.Yes — retry with backoff, reusing the same Idempotency-Key.

402 Payment Required

json
{
"success": false,
"message": "Insufficient credits. Add credits or enable auto-recharge to continue.",
"credits": {
  "available": 12,
  "cost": 25,
  "remaining": 12
}
}

A 402 can also be returned after the upstream lookup succeeded, if the wallet ran out between the pre-check and the deduction. Nothing is charged and no data is returned in that case, so treat it the same way.

503 Service Unavailable

json
{
"success": false,
"message": "Unable to verify billing."
}

Unlike a quota 429, a 503 is transient — retry it with exponential backoff. The most common cause is an auto-recharge that hasn't settled yet; it usually clears within a few seconds.

Idempotency

Send an Idempotency-Key header on any request you might retry. CarsXE deduplicates wallet deductions only when the same key is reused for the same logical request (same endpoint, parameters, and unit count), within 24 hours of the first accepted attempt. Requests without the header are billed independently, so a retry deducts a second time. This matters most on bulk submits, where one retry can cost many credits.

Usage alerts

You don't have to discover a quota 429 in production. CarsXE emails the account owner when an API reaches 80%, 90%, and 100% of its included volume, so you can upgrade or enable overage before requests start failing.

Handling 429s in code

A quota 429 is not transient — unlike a 5xx, retrying with backoff won't make it succeed. The right response depends on usage:

Handle a 429

Code
CARSXE_API_KEY="YOUR_API_KEY"
URL="https://api.carsxe.com/v1/specs?vin=1HGCM82633A004352"

response=$(curl -s -w "\n%{http_code}" -H "x-api-key: $CARSXE_API_KEY" "$URL")
body=$(echo "$response" | sed '$d')
status=$(echo "$response" | tail -n 1)

if [ "$status" = "429" ]; then
  remaining=$(echo "$body" | jq -r '.usage.remaining')
  message=$(echo "$body" | jq -r '.message')
  if [ "$remaining" = "0" ]; then
    echo "CarsXE quota exhausted: $message" >&2
    exit 1
  fi
  # Bulk request too large — shrink and retry
  echo "Retry with at most $remaining VINs" >&2
fi

Two practical patterns:

For generic retry/backoff handling of 5xx errors, see the full code samples on the Errors page.

Raising your limits