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.

<Note>
  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.
</Note>

---

## How quotas work

- **Per-API quotas.** Each API (Specs, Market Value, History, …) has its own included monthly volume, determined by your subscription tier. A few related APIs share a combined quota.
- **Monthly reset.** Usage counters reset at the start of each billing period. Trial allowances are one-time — they do not reset monthly.
- **Units, not requests.** Most requests consume 1 unit. Bulk endpoints (for example [Recalls Batch](/docs/v1/recalls-batch)) consume **one unit per VIN**, so a 500-VIN batch uses 500 units in a single request.
- **Failed validation is free.** Requests rejected with a `400` validation error (missing VIN, bad parameter, etc.) are blocked before any lookup and don't count against your quota.
- **Plan-gated APIs.** Some APIs aren't included in lower tiers at all. Calling one returns a `403` — see [Errors](/docs/errors) — not a `429`.

You can see your current usage per API at any time on the [developer dashboard](https://api.carsxe.com/dashboard/developer).

---

## What happens when you hit the limit

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.

---

## The 429 response

Quota errors use the standard [error envelope](/docs/errors) plus a `usage` object:

<PortableCode value={{
 language: "json",
 code: `{
  "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
  }
}`
}} />

<Properties>
  <Property name="usage.current" type="number">
    Units consumed so far this billing period (or in total, for one-time trial allowances).
  </Property>
  <Property name="usage.limit" type="number">
    Your included volume for this API on your current tier.
  </Property>
  <Property name="usage.remaining" type="number">
    Units left before the limit. <code>0</code> when the request was rejected.
  </Property>
</Properties>

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](https://api.carsxe.com/dashboard/developer) and the same request will succeed immediately.

---

## 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`:

<PortableCode value={{
 language: "javascript",
 code: `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:

- **Track `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.
- **Size batches to fit.** Before a bulk call, make sure the VIN count is at or below your remaining units — a rejected batch consumes nothing, but it also accomplishes nothing.

For generic retry/backoff handling of `5xx` errors, see the full code samples on the [Errors](/docs/errors) page.

---

## Raising your limits

- **Upgrade your tier** for more included volume on every API — compare plans on the [pricing page](https://api.carsxe.com/pricing).
- **Enable overage billing** to never be blocked: usage past the included volume is billed per call at your tier's rate.
- **Go enterprise** for high or spiky volume: custom quotas, custom pricing, and consolidated monthly invoicing. [Contact us](https://api.carsxe.com/contact) to talk through your numbers.