Coming soon!

 The GET/companies/{companyId}/workers endpoint will soon return a max of 50 workers per call.

Why :

This pagination, improves performance and reliability for applications querying large worker datasets. This change ensures our API scales better for all partners and your integration singularly.

What :

You will need to do update your integration to use pagination when using GET /companies/{companyId}/workers. This is specific to companies that have over 50 workers. If the request is more than 50, it will throw an error: Requested limit: {} exceeds maximum limit 

Timelines:
•     Monday, August 31st, 2026 - Initial email announcement (we will attempt to reach out via email as well, several times with the email we have on file)
•    Monday, November 30, 2026 - Prepare to decom the legacy 
•    Wednesday, February 24, 2027: Need to be fully cut-over and legacy endpoint fully deprecated - the legacy, non-paginated version of the endpoint will be permanently decommissioned by this date!

**************************************************************************************************************************************************
Rate Limiting - In the next month or so, we will be adding rate limiting to all our endpoints. We will send a communication email on this as well so you can prepare, if we have your recent contacts.

Why:

• User Satisfaction and Experience: Clear communication helps you, our consumers,  understand what to expect and how to interact with our API effectively. It prevents frustration when you hit limits and empowers you to design applications in a way that respects those limits.
   
• Preventing Misuse and Abuse: By publishing these limits, we hope to discourage deliberate abuse or accidental overloading of our API, protecting our system's health and stability for all.
  
   
• Guidance for Developers: Developers can plan their integrations better when they know the rate limits. This includes implementing strategies like request batching, understanding reset periods, and designing retry mechanisms.
  
   
• Clear Error Handling: When a limit is exceeded, it's standard practice to return a 429 Too Many Requests HTTP status code. we will provide detailed error messages that explains which limit was hit, when it will reset, and offering alternatives (like batching requests) further enhances the developer experience.
   

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

Your partner account can make up to 1,000 requests per minute

You can make 549 more requests immediately. You have already used 451 of your 1,000 quota

In 23 seconds, your bucket will be completely full again at 1,000 requests

If you receive a 429 error, wait for 4 seconds before sending your next request