# Rate limits

The limits on how often you can call the Vezmo API, covering each API key's requests a second in test and live, your plan's API requests a minute in watch and enforced mode, limits per endpoint from one address, declined-card limits, email limits, and how to handle a 429 and Retry-After.

Source: https://vezmo.com/docs/developers/rate-limits

## Overview

Several limits keep the API fast for everyone and stop card testing. A call has to fit inside every limit that applies
to it. Over one, the API answers `429 Too Many Requests`, and nothing is created or charged.

| Limit | Counted | Over it |
| --- | --- | --- |
| [Per API key](#per-api-key) | Requests a second, per key | `429` `rate_limited`, with `Retry-After` |
| [Your plan](#your-plans-api-requests-a-minute) | API requests a minute, all your keys together | Watch mode: nothing refused. Enforced: `429` `PLAN_LIMIT`, with `Retry-After` |
| [Per endpoint](#per-endpoint) | Calls to one endpoint from one address | `429` `http.429`, with `Retry-After-short`, `-medium` or `-long` |
| [Declined cards](#declined-cards) | Declines per checkout, card and network | `429` `too_many_declines` |
| [Emails](#emails) | Emails your business sends to clients and signers | `429`, or `400` for an agreement reminder sent too soon |

The codes are explained in [Errors, retries and idempotency](/docs/developers/errors-and-retries#limits).

## Per API key

Every request made with an API key counts toward that key's limit, whatever the endpoint. All our servers share one
count.

- A **live key** allows 100 requests a second by default.
- A **test key** allows 25 requests a second by default.

Over it, the call answers `429` with the code `rate_limited`, a `Retry-After` header in seconds, and the same number in
`errors[0].retryAfter`. Your checkout pages don't use your API key, so your customers' payments
don't count toward it.

Taking an invoice's card payment with your key (`POST /merchant/invoice/:id/pay`) also has its own limit per key: 5 a
second and 60 a minute.

## Your plan's API requests a minute

Your plan also sets how many API requests your business makes a minute, all your keys together. Test and live keys
count apart, each against the same number. A minute is a calendar minute in UTC: the count starts again at the top of
each minute. Your plan's number is in **Plan & billing** (see [Plans and billing](/docs/get-started/plans-and-billing)),
with your busiest minute today.

The limit runs in one of two modes:

- **Watch mode**: a request past the number still goes through, and is only recorded.
- **Enforced**: a request past the number answers `429` with the code `PLAN_LIMIT`, and a `Retry-After` header with
  the seconds until the next minute. `errors[0]` says what was used, what your plan allows, and which plan has more.

Handle `PLAN_LIMIT` now, so nothing changes for you on the day it is enforced.

## Per endpoint

Some endpoints also limit how often one address calls them. For your server that address is your server's, so these
limits are shared by all your customers' checkouts. Every window has to have room.

| Endpoint | Limit from one address |
| --- | --- |
| Sign in (`POST /merchant/api-auth/login`) | 5 a minute |
| Create a checkout session (`POST /merchant/secure-payments`) | 10 a second, 30 in 10 seconds, 60 a minute |
| Refund or cancel a payment | 5 a second, 20 in 10 seconds, 40 a minute |
| The other payments endpoints (`/merchant/payment…`) | 3 a second, 20 in 10 seconds, 60 a minute (the bank deposit check has tighter limits) |
| Subscriptions (`/merchant/subscription…`) | 3 a second, 20 in 10 seconds, 60 a minute |
| Agreements: every change (create, upload, send, remind, void, delete, ID checks, complete) | 2 a second, 10 in 10 seconds, 30 a minute |
| Agreements: templates, list, get, audit trail, document | 3 a second, 20 in 10 seconds, 60 a minute |

Over one, the call answers `429` with the code `http.429`. The wait is in a header named after the window that ran
out: `Retry-After-short` (the one-second window), `Retry-After-medium` (10 seconds) or `Retry-After-long` (a minute).
Each answer from these endpoints also carries `X-RateLimit-Limit-…`, `X-RateLimit-Remaining-…` and
`X-RateLimit-Reset-…` headers for each window, so you can slow down before you reach one.

Two habits keep you clear of them:

- **Reuse your access token** for its 30 minutes. Signing in once per call reaches the 5-a-minute sign-in limit fast.
- **Create a checkout session when the customer is ready to pay**, not ahead of time. 60 sessions a minute from one
  address is the ceiling for your whole store.

Every limit, including the ones on your customers' payment pages: [Limits in the API reference](https://user.vezmo.com/docs/v1/limits).

## Declined cards

Card testers try stolen card numbers on checkout pages to find the ones that work. Every card payment on Vezmo, on
every checkout, shares the same limits on declined cards: per checkout, per card, and per network address. A limit
counts declines only; a successful payment never counts.

At a limit, the payment answers `429` with the code `too_many_declines` before anything is charged, and
`errors[0].reason` says which limit: `checkout` (this payment), `card` (this card) or `network` (your customer's network).
Show your customer the `message` as it is, and don't retry the card. When your server takes an invoice's payment with
your API key, the network limit doesn't apply: the address is your server's.

If a business's card payments are being tested (many declines in a short time), Vezmo asks 3D Secure on its customers'
card payments for a while.

In test mode the counts are kept apart from live: the checkout and network limits still answer `429`, so you can see
one, but no card is blocked and 3D Secure is never forced.

The numbers, by default: [Declined cards in the API reference](https://user.vezmo.com/docs/v1/limits).

## Emails

Emails we send to your clients and signers from Vezmo's address have limits per business:

- **Send invoice** and **Send proposal**: one email per invoice or proposal a minute.
- **Invoice and proposal emails**: one daily count for both together, per business, CC copies included.
- **Agreement invitations and reminders**: their own daily count, per business.
- **Agreement reminders**: once a minute per agreement.

If you need a higher daily count, ask [support](https://user.vezmo.com/supports) to raise it. Over a limit, the call answers
`429` and the `message` says the limit; a reminder sent within the minute answers `400` and says how long to wait. In test mode, an email to someone outside your team
is skipped, and a skipped email doesn't count.

## Handle a 429

1. **Wait.** Use `Retry-After` when it is there (or `errors[0].retryAfter`); for a per-endpoint limit, the
   `Retry-After-short`, `-medium` or `-long` header. Without one, back off: about 1 second, then 2, then 4, with a little
   randomness.
2. **Retry only what is safe to repeat**: reads, and the calls that take an `Idempotency-Key`, with the same key. See
   [When to retry](/docs/developers/errors-and-retries#when-to-retry).
3. **Don't retry `too_many_declines`.** It is about the card or the customer, not your pace.
4. **Spread the load.** If you reach a limit often, batch your reads, cache what doesn't change, and act on
   [webhooks](/docs/developers/webhooks) instead of asking the API again and again.

## Questions

### Do test calls count toward my live limits?

No. A test key has its own per-key limit, test calls count apart for your plan's limit, and test declines don't count
toward live card limits.

### Do my customers' payments count toward my API limits?

No. Your checkout pages, payment links and invoices don't use your API key. Only calls your server
makes with a key count.

### Can my limits be raised?

Your plan's API requests a minute changes with your plan: see [Plans and billing](/docs/get-started/plans-and-billing).
For the email limits, ask [support](https://user.vezmo.com/supports).

## Related

- [Errors, retries and idempotency](/docs/developers/errors-and-retries)
- [API keys and access tokens](/docs/developers/api-keys)
- [Hosted checkout](/docs/developers/hosted-checkout#limits)
- [Limits in the API reference](https://user.vezmo.com/docs/v1/limits)