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.

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.

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.