These docs are retiring to docs.carsxe.com. This site will be decommissioned on October 1, 2026.
Go to new docsHow 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.
dimension=variants + year + make → 1 unit per model; see modelCount).400 validation error (missing VIN, bad parameter, etc.) are blocked before any lookup and don't count against your quota.Credit-wallet accounts should send an Idempotency-Key header on retried requests. An API key authenticates a request but does not deduplicate it. CarsXE deduplicates wallet deductions only when the same Idempotency-Key is reused for the same logical request; requests without that header are billed independently. This is especially important for batch submits.
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 Sandbox lifetime 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 (Sandbox) 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.