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.
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 | Requests a second, per key | 429 rate_limited, with Retry-After |
| Your plan | API requests a minute, all your keys together | Watch mode: nothing refused. Enforced: 429 PLAN_LIMIT, with Retry-After |
| Per endpoint | Calls to one endpoint from one address | 429 http.429, with Retry-After-short, -medium or -long |
| Declined cards | Declines per checkout, card and network | 429 too_many_declines |
| 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.
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), 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
429with the codePLAN_LIMIT, and aRetry-Afterheader 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.
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.
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 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
- Wait. Use
Retry-Afterwhen it is there (orerrors[0].retryAfter); for a per-endpoint limit, theRetry-After-short,-mediumor-longheader. Without one, back off: about 1 second, then 2, then 4, with a little randomness. - Retry only what is safe to repeat: reads, and the calls that take an
Idempotency-Key, with the same key. See When to retry. - Don't retry
too_many_declines. It is about the card or the customer, not your pace. - Spread the load. If you reach a limit often, batch your reads, cache what doesn't change, and act on 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. For the email limits, ask support.
Related
Facts checked against the product on 9 Nov 2026.
Was this page helpful?
Errors, retries and idempotency
How the Vezmo API reports errors, covering the error body, requestId and X-Request-Id, what each status means, the error codes by area, which calls take an Idempotency-Key and how it behaves, when and how to retry, two GET routes not to repeat, and paging through lists with page or cursor.
API changelog
Dated changes to the Vezmo API, webhooks and browser SDKs, newest first, with deprecated routes and how changes reach you, from API key expiry reminders and plan limits to the V2 webhook signature, the Agreements API and the payment link permission change.