Rate Limiting
Coming soon later this September!...
Rate Limiting w/ Paychex API's
If your application makes a significant number of API requests in a short period of time, it may receive a 429 Too Many Requests error response from the Paychex API. This indicates that your application has reached our API rate limit. We implement rate limits to maintain the reliability and performance of our API for all partners and to encourage responsible usage.
Paychex API Rate Limits
The Paychex API rate limit is applied currently on a per-partner basis, with limits calculated over a per-minute window and including a per-second burst allowance.
- General Limit: Currently, the API rate limit is set to 10,000 requests per minute per partner, but we suggest looking into the response header to determine, as this may change in the future!
- Per-Second Burst: You are also permitted a per-second burst up to 1/5th of the per-minute rate, meaning you can make up to 2,000 requests per second.
If your application exceeds these limits, you will begin to see 429 Too Many Requests error responses from the Paychex API. This can lead to unexpected behavior within your application if not handled gracefully.
Example Scenario:
- If your application sends 10,000 requests within a single minute, the 10,001st request within that same minute will receive a 429 Too Many Requests response.
- Similarly, if your application attempts to send more than 2,000 requests within a single second, any subsequent requests in that second will also trigger a 429 Too Many Requests response, even if the per-minute limit has not yet been reached.
Response Headers
- Successful responses include the first three headers (X-RateLimit-*)
- 429 (Too Many Requests) error responses will also include the Retry-After header.
Understanding Rate Limit Headers
| X-RateLimit-Limit | Maximum number of requests allowed per minute for your application | 10000 | Your application can make up to 10,000 requests per minute |
| X-RateLimit-Remaining | How many more requests you can make right now before you'll start getting rate-limited. | 549 | You can make 549 more requests immediately. You have already used 451 of your 10,000 quota |
| X-RateLimit-Reset | Seconds until the bucket fully refills to maximum capacity (informational only) | 23 | In 23 seconds, your bucket will be completely full again at 10,000 requests |
| Retry-After | Wait this many seconds before retrying | 4 | If you receive a 429 error, wait for 4 seconds before sending your next request |
Fail-Open Scenarios
What is "Fail-Open"?
Fail-open means that if the rate limiting system experiences an outage, timeout, or misconfiguration, the gateway will allow requests to pass through instead of blocking them. This ensures your service remains available even during Redis outages or system issues.
Frequently Asked Questions
Q: Can I have different limits for different endpoints?
A: Currently, rate limits apply uniformly across all API endpoints for a given application.
Q: What happens if I exceed my rate limit?
A: You'll receive HTTP 429 responses with a Retry-After header indicating when to retry. Your requests are not lost; retry after the specified delay.
Q: Do rate limit headers appear on error responses (4xx, 5xx)?
A: Yes, rate limit headers appear on all responses when rate limiting is active, including error responses.
Q: How often does my rate limit bucket refill?
A: The bucket refills continuously, not at fixed intervals. The X-RateLimit-Reset header shows when the bucket will be fully replenished.
Q: What if I use the same Partner key across multiple applications or integrations?
A: All requests made with the same Partner key share a single rate limit, regardless of which application or system sends them. If you're running multiple integrations under one Partner ID, their combined traffic counts against the same limit.