Learn how Sail's per-minute and per-second request limits work, and how to handle a 429 response.
Sail limits how many requests you can send so that no single integration can affect service for others. This page explains how the limits are applied, how to read your current standing from the response headers, and what to do when you exceed a limit.
How limits are applied
Limits apply per API key and per endpoint. Each endpoint has its own budget, so paging through expenses never uses up the capacity you need for pushing transactions.
Each endpoint has two windows running at the same time:
- A sustained per-minute budget, which covers your normal traffic.
- A per-second burst ceiling, which stops a full minute of requests from arriving at once.
A request must fit within both windows. If either one is full, the request is rejected.
Endpoint limits
Write-heavy endpoints have lower budgets than the rest of the API. The following limits apply to each of your API keys.
| Endpoint | Per minute | Per second |
|---|---|---|
| Create Users in Bulk | 100 | 5 |
| Push Transactions | 100 | 5 |
| Create User | 300 | 15 |
| All other endpoints | 600 | 25 |
Create Users in Bulk accepts up to 500 users per request, so a backfill costs far fewer requests than calling Create User in a loop.
Rate limit headers
Every response tells you where you stand, so you can pace your requests instead of guessing. The headers describe the sustained per-minute window.
RateLimit-Limit: 600
RateLimit-Remaining: 594
RateLimit-Reset: 37
RateLimit-Policy: 25;w=1, 600;w=60| Header | Description |
|---|---|
RateLimit-Limit | Your total budget for the sustained window. |
RateLimit-Remaining | Requests left in the current sustained window. |
RateLimit-Reset | Seconds until the sustained window rolls over. |
RateLimit-Policy | Every window in force, as limit;w=seconds. In the example above, 25 requests per 1 second and 600 per 60 seconds. |
When you exceed a limit
Going over either window returns 429 rate_limited with a Retry-After header, given in seconds. Retry-After refers to the window that actually blocked the request, so a burst rejection asks you to wait a second rather than a minute.
Wait for the period given in Retry-After, then retry with exponential backoff. Polling through a 429 without waiting keeps you throttled.
Abuse protection limits
Two more limits apply before Sail reads your API key. They exist to contain abuse, not to shape normal traffic, and a correctly configured integration won't reach either one:
- A ceiling on requests from a single source address.
- A lockout after repeated authentication failures from one address.
Deploy the new key before you revoke the old one. Retries that present a revoked credential count as authentication failures and can trigger the lockout.
Requesting a higher budget
If a migration or a backfill needs more capacity than these limits allow, contact Sail to discuss a higher budget. Splitting the work across parallel API keys to work around the limits is not supported.
Next steps
- To handle rejected requests, see Errors for the full status and error code catalog.
- To understand which key scope each endpoint needs, see Authentication.