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/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, a404, a409(inviting the admin of a suspended customer, redelivering to a paused endpoint) or a422. 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
500was still sent. - A call answered from its
Idempotency-Keyis 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=100when reading whole lists. - Need more for a migration or a large import? Ask your Monotree contact.