Rate limits
There is no fixed limit on requests per second for an API key today. Send at the pace your work needs. To send many deliveries at once, use a batch rather than thousands of single calls: one request, and Parasend paces the notices.
Some actions have limits of their own. Each answers 429 with a code that says which limit was reached:
| Limit | Code | What to do |
|---|---|---|
| The key's monthly cap of deliveries, if you set one in API keys | monthly_ | Raise the cap in the portal, or wait for the next month. |
| The free plan's daily number of deliveries | free_ | Choose a plan in the portal, or wait until tomorrow. |
| Your monthly spending cap, if you set one | spending_ | Raise the cap in the portal, or wait for the next month. |
| Manual reminders: 10 per recipient a day | remind_ | Try again tomorrow. Automatic reminders from the follow-up policy do not count. |
| The record check: 120 lookups an hour from one address, and 20 lookups that find nothing in 10 minutes | rate_ | Wait the seconds in Retry-After. |
Limits on test-mode deliveries follow the key's own cap only: test mode is never billed, so the free and spending limits do not apply to it.
Headers
An endpoint with a fixed limit, such as the record check, tells you where you stand on every answer:
| Header | What it says |
|---|---|
RateLimit-Limit | How many requests the window allows. |
RateLimit-Remaining | How many are left in this window. |
RateLimit-Reset | Seconds until the window starts again. |
Retry-After | On a 429: seconds to wait before trying again. |
Handling a 429
Wait as long as Retry-After says when it is there; otherwise back off exponentially, starting at one second. Retry a POST with the same Idempotency-Key, so a retry can never send twice. A 429 for a cap or a plan limit will not clear by waiting a few seconds: the code says which it is, so show it to a person instead of retrying in a loop.