Rate Limits & Quotas

Two mechanisms, two 429s

Both kinds of 429 are never billed and never consume quota.

Rate limiting

Each account has a token bucket (requests per second with a burst allowance, sized by plan). Every authenticated response reports the bucket state:

RateLimit-Limit: 100
RateLimit-Remaining: 97
RateLimit-Reset: 1

Pace against RateLimit-Remaining proactively; on a 429, honor Retry-After (seconds) with jittered backoff rather than immediately retrying.

Per-key rate limits

The plan's rate applies to your whole account: all your API keys and OAuth clients share it, so adding keys never adds capacity. Each key also has its own fairness bucket, so one busy key cannot starve the others.

You can give a single key a lower rate and burst than the plan, for example to keep a batch importer from crowding out interactive traffic. Workspace admins and owners set this per key in the portal. The values may only be lowered: anything above the plan's rate or burst is refused. Clear a value and the key follows the plan again. The account-wide limit always stays at the plan, whatever the per-key settings say. To run a key above the plan rate, contact support.

A key's override is kept when you rotate it.

Included quota (live keys)

Your plan includes a per-period conversion allowance for live keys, counted across all your live keys together. On paid plans the counting window is your own billing period — the anniversary cycle your Stripe subscription renews on — so what the dashboard shows always matches what Stripe bills. On Free (no subscription) the window is the UTC calendar month. The two headers on every metered response show where you stand — X-Quota-Remaining is the count before the current request, clamped at zero, and GET /v1/usage reports the window itself as period_start / period_end (with resets_at = period_end).

Hard-stop vs overage:

• Free is hard-stop: at 1,000 live conversions/month further metered requests get quota-exceeded until the month resets. The error detail names your quota and the reset time.
• Paid plans allow overage by default: requests are never blocked; past the included allowance, X-Quota-Remaining sits at 0 and additional billable conversions are metered at your plan's overage rate (pre-tax, in your billing currency).
• Paid plans with a spend cap: you can opt into a hard stop or a spend ceiling yourself — see Spend Caps & Usage Alerts. When one of your caps is reached, metered requests get quota-exceeded with a detail naming the cap, until you raise it or upgrade.

The one-time test allowance (test keys)

Test keys don't touch the monthly quota. Instead, every account has a one-time pool of 250 test requests — lifetime, shared by all your test keys and test OAuth clients, identical on every plan, and it never resets. On test-key responses, X-Quota-Limit reports 250 and X-Quota-Remaining counts down the pool; when it's spent, metered routes answer quota-exceeded on every plan (overage never applies to the pool). GET /v1/usage reports the pool as test_quota / test_used / test_remaining. See Test vs Live Keys for the rationale.

What counts against either pool follows the billing rules in Test vs Live Keys: 2xx and content-level 400/422 responses count; auth failures, 429s, 5xxs, and idempotent replays never do.

Current plan tiers, included volumes, and overage pricing are on the pricing page.

Batch size per request

POST /v1/convert/batch accepts a limited number of items in one request, set by your plan: 50 items on Free, more on paid plans, and never more than 500 on any plan. A batch over your limit is rejected whole with invalid-input before anything is queued; the detail names the limit and your plan. Split larger workloads into several batches. See Batch & Jobs.

If the plan lookup itself fails, the limit falls back to 500 rather than refusing your batch.

Monthly accounting-post allowance

Posting transactions into your books through an accounting connection has its own monthly allowance, separate from the conversion quota. It counts transactions posted in the calendar month (UTC); re-sending a transaction that was already posted does not count again. Free includes 100 posts a month; paid plans include more. When it is used up, posting answers post-quota-exceeded 429 until the next month or an upgrade.

Unlike the conversion quota, this check fails closed: if the allowance cannot be checked, the post is refused with internal rather than risk an unbounded post. Dry-runs (previews) do not post and do not count.

Changing plans

Change your plan anytime from the portal's billing page.

Upgrades take effect immediately and charge the full price difference between the two plans for the current cycle (pre-tax; applicable tax is added on top) — not a time-proration. Because the new plan's full included volume applies to the whole billing period (included volumes are never time-prorated), the upgrade costs the same whether you switch on day 1 or day 29: it is simply the new plan's flat price minus your current plan's flat price. Your billing date does not move. Your new, larger allowance applies from the moment you confirm, and the conversions you have already used this period carry over and count against it — so upgrading mid-period never double-charges you for usage you already ran. Any overage that had accrued at your old plan's rate before the upgrade is forgiven: upgrading wipes that slate clean rather than carrying an old-rate charge forward.

Downgrades take effect at the end of your current period. You keep your current plan (and its allowance) until the period ends, then the smaller plan starts on the next renewal — so a downgrade never retroactively creates overage against a lower allowance. The portal shows the exact date the change will apply.

The Scale plan is billed by bank direct debit only — ACH in the US (USD), SEPA in the eurozone (EUR), or Bacs in the UK (GBP), following your billing currency. If you don't already have a bank account on file, the upgrade flow sends you through Stripe's secure setup to add one and then returns you to the billing page to finish the upgrade — you don't lose your place. Once you're on Scale, the upgrade charge and every renewal debit that bank account, and a card can't be set as your default while on Scale. Bank debits settle over a few days rather than instantly, so a fresh charge (including an upgrade to Scale) can show as pending until it clears; your larger allowance still applies from the moment you confirm. You can add or switch bank accounts, and pick which one is the default, from the Payment methods section on the billing page.

Activation is immediate on every plan — you can start using your new allowance the moment you confirm the change. On Scale, because bank debits take 3–6 business days to settle, the plan runs on introductory limits until your first payment settles; once it clears, your full Scale limits unlock and we email you to confirm. If your first-ever payment fails, that forfeits the grace period: service runs at Free limits until a successful payment settles, rather than at your paid allowance. Every settled payment produces a receipt by email with a link to the Stripe-hosted invoice, which you can also open any time from the Invoices table on the billing page.

A resilient client, in five lines of pseudocode

if 429 and type == rate-limited:   sleep(Retry-After + jitter); retry (idempotency key set)
if 429 and type == quota-exceeded: alert billing owner; pause metered work until reset/upgrade
if RateLimit-Remaining < 10%:      slow producer
if X-Quota-Remaining < threshold:  warn early — don't discover exhaustion at the hard stop

Fail-open, for the record

The limiter and quota checks are engineered to fail open: if our billing store has an outage, your conversions keep flowing — a billing outage will never become an API outage for you.