How CarsXE usage limits work — included monthly volume, the 429 response shape, overage billing, usage alerts, and how to handle limits in code.
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.
400 validation error (missing VIN, bad parameter, etc.) are blocked before any lookup and don't count against your quota.403 — see Errors — not a 429.You can see your current usage per API at any time on the developer dashboard.
There are two possible behaviors, controlled by your overage billing preference in the dashboard:
| Overage billing | Behavior 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.
Quota errors use the standard error envelope plus a usage object:
{
"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
}
}usage.currentUnits consumed so far this billing period (or in total, for one-time trial allowances).
usage.limitYour included volume for this API on your current tier.
usage.remainingUnits left before the limit. 0 when the request was rejected.
The message tells you which API hit its limit, the billing period (month/year), your tier, and the exact numbers. Variants you may see:
This request requires N units. — appended when a bulk request would exceed the limit even though current < limit. Reduce the batch size to fit within remaining, or split it across billing periods.Please upgrade your tier to continue using the API. — appended for one-time (trial) allowances that never reset. Waiting won't help; upgrade to continue.Enable overage billing in your dashboard billing preferences to continue with overage charges: … — appended when you've opted out of overage but your plan supports it. Re-enable overage on the developer dashboard and the same request will succeed immediately.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.
A quota 429 is not transient — unlike a 5xx, retrying with backoff won't make it succeed. The right response depends on usage:
const res = await fetch(url);
const body = await res.json();
if (res.status === 429) {
if (body.usage?.remaining === 0) {
// Quota exhausted: retrying is pointless this billing period.
// Alert your team — fix is upgrading, enabling overage, or waiting for reset.
notifyOps(`CarsXE quota exhausted: ${body.message}`);
throw new Error(body.message);
}
// Bulk request too large for what's left — shrink and retry.
return sendSmallerBatch(body.usage.remaining);
}Two practical patterns:
usage.remaining proactively. It's returned on quota errors, and your live numbers are always on the dashboard. Alerting at your own threshold (say 75%) gives you more lead time than the built-in emails.For generic retry/backoff handling of 5xx errors, see the full code samples on the Errors page.