Overview of API Rate Limits
Rate limiting is a crucial aspect of API management, as it ensures the stability and performance of API endpoints by preventing abuse or overconsumption of resources.
Paylocity API Rate Limiting Strategy
We have set a general rate limit for Weblink API users, permitting up to 25 calls per second.
Certain operations have lower, endpoint-specific rate limits to protect API performance and reliability. These additional limits apply separately to each HTTP operation and are listed below.
Weblink API users must comply with both the general limit and any applicable operation-specific limit.
Building with multiple APIsThe rate limit for Weblink API is different than the limits used for other APIs.
If using multiple APIs for your integration it is best practice to observe both rate limit rules.
If an API user exceeds these limits, they will receive a 429 Too Many Requests error, indicating the client has made too many requests.
See: API Error Handling
Endpoint-Specific Rate Limits
| API Operation | API Name | Rate Limit (calls per second) |
|---|---|---|
| POST | Create New Employee | 3 |
| PATCH | Update Employee | 3 |
| POST | Create Employee Onboarding | 3 |
| POST | Upsert Deduction | 20 |
| PUT | Upsert Emergency Contacts | 3 |
| PUT | Upsert Sensitive Data | 5 |
Preventing and Handling Rate Limit Threshold Errors
To ensure seamless integration and prevent receiving an HTTP 429 error response due to exceeding rate limits, developers should implement the following strategies:
- Design Efficient Code: Optimize your code to minimize the number of API calls made within a time window, staying within the allowed limit. This can involve caching data, reducing redundant requests, and only requesting the data you need. You can facilitate Paylocity webhooks to be notified about changes in entities and only make the API call once a webhook notification has been received.
- Implement Rate Limiting Logic: Add logic in your code to track and limit the number of API calls made within a time window. This can be achieved using various techniques, such as the leaky bucket algorithm, depending on your specific use case. Algorithms that are based on, or allow bursting, such as the token bucket algorithm, are not recommended. We recommend spreading out the traffic uniformly over a longer time period, rather than sending short, large bursts of requests.
- Handle Error Responses Gracefully: If an error occurs, implement a retry mechanism in your code to pause and retry the API call later. This can involve exponential back-off algorithms to progressively increase the waiting time between retries and ensure that the API is not overwhelmed. When using the exponential back-off, add a random jitter to each back-off iteration so you are not creating the same rate limiting effect later. It is also recommended to implement the “poison pill” design pattern to terminate the retry iteration after several failed attempts of the same request.
By following these best practices, development teams can prevent and handle rate limiting issues when building integrations using our APIs. This will help maintain the stability, reliability, and performance of both the API and the integrated applications, leading to a better user experience for our mutual customers and streamlined HR processes.