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 (employee data)	People endpoints rate limits
Onboarding wizards	Onboarding endpoints rate limits
Metadata (employee fields)	Metadata endpoints rate limits
Employee Tables (employee data)	Employee tables endpoints rate limits
Custom Tables (employee data)	Custom tables endpoints rate limits
Time off requests	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
Tasks	Tasks endpoints rate limits
Reports	Reports endpoints rate limits
Docs	No rate limits are implemented at the moment
Goals	Goals endpoints rate limits
Job catalog	Job catalog endpoints rate limits
Workforce Planning	Workforce Planning endpoints rate limits
Hiring	Hiring 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 or 403 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.