Conventions

Rate limits

120 requests a minute per partner and mode, with headers that say how many are left.

You may make 120 requests a minute. The count is per partner and mode: all your live tokens share one count, and all your sandbox tokens share another. Creating more tokens does not give you more calls.

Before the token is checked, each IP address is also limited to 300 requests a minute. This stops someone from guessing tokens. You only notice it if several systems call from the same address.

Every answer to a call with a token says where you are in that minute:

Header
X-RateLimit-Limit Requests allowed per minute: 120
X-RateLimit-Remaining Requests left in this minute

These two are always about the general limit of 120 a minute, also on a call that has a lower limit of its own: a lower limit has no headers until you are over it.

Over the limit, the API answers 429 with the type rate_limited and two more headers:

Header
Retry-After Seconds to wait before the next call
X-RateLimit-Reset When the minute ends, as a Unix time
HTTP
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
Retry-After: 41
X-RateLimit-Reset: 1794659400

{"error":{"type":"rate_limited","message":"Too many requests. Wait for the number of seconds in the Retry-After header."}}

Wait the number of seconds in Retry-After, then go on. A call that was refused with 429 did nothing, so it is safe to send again.

Towards the 120 a minute, a call counts as soon as its token is accepted, also when it then fails for another reason, such as a 422.

Lower limits for some calls

Calls that send email, that ask Monotree's people for something, or that make our servers call yours, have a lower limit of their own on top of the 120 a minute. Over it, the answer is a 429 rate_limited with Retry-After (here often minutes instead of seconds) and without the X-RateLimit-Reset header; message may say when to try again.

A lower limit counts what was done, not what was asked:

  • A call that is refused before anything happened uses up no place: a 403, a 404, a 409 (inviting the admin of a suspended customer, redelivering to a paused endpoint) or a 422. So a refusal never makes the next, correct call wait.
  • A call that did the thing counts, whatever came of it: a test event your server answered with a 500 was still sent.
  • A call answered from its Idempotency-Key is the first call's answer and counts nothing.
  • The portal's buttons count in the same limit as the API's calls: an invitation sent again in the portal is one of the seller's three an hour.
  • In the sandbox, an invitation to a seller is not sent and not counted.

Two exceptions, where the answer itself is what is limited: adding a seller, and changing a seller's email, also count when they are refused because of the address (422), so addresses cannot be tried out by the thousand.

Call Limit Counted per
Add a seller that sends an invitation (not with invite: false, and not in the sandbox) 30 an hour Partner and mode
Add a seller with invite: false, and every seller added in the sandbox 60 an hour Partner and mode
Send a seller's invitation, and Update a seller with invite: true or with a new email 3 an hour Seller
Update a seller with a new email 30 an hour Partner and mode
Create a customer with a seller_ref that is an email address none of your sellers has (it adds a seller) 60 an hour Partner and mode
Reset a seller's two-factor 5 an hour Seller
Send the admin invitation again 1 every 10 minutes Customer
Change a customer with a new admin.email, once the customer is submitted (a new address is a new invitation) 3 a day Customer, for tokens
Start a support thread by email (channel: email) 30 an hour Partner and mode
Answer a thread, send a draft or send a failed answer again, in a thread by mail 20 an hour, and 200 an hour Thread, and partner and mode
The same three calls in a thread by chat 600 an hour Partner and mode
An answer or a new thread by mail, counted by the people it goes to: the person and every address on copy 60 recipients an hour, and 1,000 an hour Thread, and partner and mode (the portal's answers count too)
Answer a thread with attachments 30 an hour, and 500 MB of files a day Partner and mode
Escalate a thread 20 an hour Partner and mode
Simulate a thread 60 an hour Partner and mode
Send a test event and Redeliver a delivery, together 10 a minute Webhook endpoint
Redeliver all failed deliveries 10 an hour Webhook endpoint
Rotate a signing secret 10 an hour Webhook endpoint

Every one of these counts is kept per partner and mode, like the general limit: live and sandbox never share one. A limit that is counted per seller, customer, thread or endpoint counts the thing itself, however you name it: its ID and external_ref: and your own reference are one count. An ID is only understood exactly as the API gives it out (cus_… in lower case, with its prefix); any other spelling answers 404.

Staying under it

  • Use webhooks instead of polling customers for their state.
  • When you must poll a customer that is being set up, every 3 to 5 seconds is plenty; it is usually live within a minute.
  • Use limit=100 when reading whole lists.
  • Need more for a migration or a large import? Ask your Monotree contact.