Rate Limiting

To ensure stability and availability for all users, the Sibill APIs enforce limits on the number of requests a client can make within a given time window. When the limit is exceeded, additional requests are temporarily rejected until the window resets.

Rate limiting is applied per authentication token: each token has its own independent request quota.

Response headers

Every API response includes a few HTTP headers that allow you to monitor your quota usage and react properly when the limit is reached.

Header	Description
x-ratelimit-limit	Maximum number of requests allowed in the current time window.
x-ratelimit-remaining	Number of requests still available in the current time window.
retry-after	Number of seconds to wait before making a new request. Returned only when responding with a 429.

Exceeding the limit

When the number of requests exceeds the allowed limit, the APIs respond with the HTTP status code 429 Too Many Requests. In this case, the x-ratelimit-remaining header will be 0, and the retry-after header will indicate the number of seconds to wait before retrying.

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
x-ratelimit-limit: 100
x-ratelimit-remaining: 0
retry-after: 30

{
   "errors":[
      {
         "code":"too_many_requests",
         "detail":"Rate limit exceeded. Retry after 30 seconds.",
         "title":"Too Many Requests"
      }
   ]
}

How to handle rate limiting

To avoid 429 errors and properly handle the rate limit being reached, it is recommended to follow these practices:

• Monitor the headers: check x-ratelimit-remaining to know how many requests you still have available in the current window and adjust your call frequency accordingly.
• Respect the retry-after header: when you receive a 429 response, wait the number of seconds indicated before retrying the request. Do not retry earlier, as new requests will be rejected as well.
• Implement a retry strategy with backoff: if you receive repeated 429 errors, use an exponential backoff mechanism to spread requests over time and avoid saturating the limit again.
• Avoid unnecessary parallel requests: batch your calls when possible and use pagination and filters to reduce the total number of requests.

Handling example

Below is an example of how to handle a 429 response in pseudocode:

response=$(curl -i --request GET \
     --url {{BASE_URL}}/api/v1/companies \
     --header "Authorization: Bearer {{TOKEN}}")

status=$(echo "$response" | head -n 1 | awk '{print $2}')

if [ "$status" = "429" ]; then
   retry_after=$(echo "$response" | grep -i "^retry-after:" | awk '{print $2}' | tr -d '\r')
   echo "Rate limit reached. Retrying in ${retry_after} seconds..."
   sleep "$retry_after"
fi