Learn how we limit access to endpoints and to our server
Rate limits define how many times an API user can access specific endpoints within a given time frame. Authorization-based blocking (WAF limits) adds another layer of protection by identifying and stopping patterns of failed authentication or permission requests that could indicate misconfigured integrations or abusive behavior.
This article explains how Bob protects access to its API infrastructure and shares best practices for developers to manage usage effectively and avoid interruptions.
Rate limiting best practices
To ensure the stability and reliability of our platform, we have implemented rate limiting on API endpoints. These rate limits are designed to prevent misuse and overloading of the API. Following these limits helps maintain optimal performance and availability for all users of the platform.
Bob's API rate limit determines how many API calls can be made per minute. For example, thev1/people/search
endpoint allows 50 requests per minute. If you exceed this limit, you'll get an HTTP status code of 429, meaning too many requests.
By following some best practices, you can efficiently manage your API usage and avoid disruptions due to rate limiting.
- Understand limits: Familiarize yourself with the rate limits for each API endpoint. Check the API documentation regularly for updates.
- Optimize requests: Optimize your requests to minimize the number of API calls. Use bulk operations when available to reduce the frequency of requests.
- Handle rate limit errors: Implement error handling for rate limit responses (e.g., HTTP 429 Too Many Requests) and check rate limit headers to include retry logic after the specified delay.
- Monitor usage: Continuously monitor your API usage to ensure you stay within limits. Set up alerts to notify you when you're approaching rate limits.
- Distribute requests: If possible, distribute your requests evenly over time rather than sending large bursts of requests.
- Cache responses: Cache responses when possible to reduce the need for repeated requests for the same data.
Utilize rate limit headers
In addition to seeing your rate limit on your account page, most Bob endpoints send important information about your rate limits such as the remaining limits, in the headers of the HTTP response. These headers provide information about your current usage and remaining quota.
You can expect to see the following header fields:
X-RateLimit-Limit
: The total number of requests allowed within a specific time frame.X-RateLimit-Remaining
: The number of requests you have left in the current rate limit window.X-RateLimit-Reset
: The time when the rate limit window resets, given in Unix epoch time.
Check the rate limit headers when integrating with Bob empowers you to regularly monitor usage, handle limits gracefully with a retry mechanism to pause requests until the limit resets, and optimize your requests to reduce unnecessary calls to stay within limits and ensure efficient API usage.
Rate Limits per endpoint
To learn more about the rate limits for each endpoint, click the relevant link below..
API Category | Rate Limiting Link |
---|---|
People | People endpoints rate limits |
Onboarding | Onboarding endpoints rate limits |
Reports | Reports endpoints rate limits |
Tasks | Tasks endpoints rate limits |
Metadata | Metadata endpoints rate limits |
Time off | Time off endpoints rate limits |
Time off policies | Time off policies endpoints rate limits |
Time off balance | Time off balance endpoints rate limits |
Attendance | Attendance endpoints rate limits |
Payroll | Payroll endpoints rate limits |
Documents | No rate limits are implemented at the moment |
Hiring | Hiring endpoints rate limits |
Employee Tables | Employee tables endpoints rate limits |
Custom Tables | Custom tables endpoints rate limits |
Workforce Planning | Workforce Planning endpoints rate limits |
Authorization-based blocking (WAF limits)
In addition to standard per-endpoint rate limits, Bob applies security protections at the infrastructure level using a Web Application Firewall (WAF). These limits are designed to prevent excessive failed authentication or permission requests, which can indicate misconfigured integrations or abusive behavior.
These rules are not tied to specific endpoints and are enforced separately from standard rate limits:
Condition | Result |
---|---|
More than 50 requests with HTTP 401 response from the same IP address within 10 seconds | The IP is blocked for 5 minutes |
More than 50 requests with HTTP 401 response from the same Authorization header within 10 seconds | The IP is blocked for 5 minutes |
More than 50 requests with HTTP 403 from the same Authorization header to api.hibob.com within 10 seconds | The IP is blocked for 5 minutes |
How to avoid being blocked
- Ensure your API token or service user credentials are valid and not expired.
- Do not retry failed
401
or403
requests. Instead, stop calling the API for those credentials and check them with the client. - Handle authorization and permission errors gracefully in your integration logic.
- Review and test your integration thoroughly before running it in production.
If any of these rules change, we'll update the changelog. We recommend subscribing to the changelog to stay informed.