🚦 Rate Limits
Last updated

API Rate Limits

To ensure fair usage and maintain the stability and performance of our API, Boya implements rate limiting on all API endpoints. This document outlines our rate limit policy and provides guidance on how to work within these limits.

Table of Contents

Default Limits

By default, the following rate limits apply to all API keys:

  • Requests per second: 10
  • Requests per day: 86,400 (equivalent to 1 request per second over 24 hours)

These limits are applied on a per-API key basis, not per user or per application.

Understanding Rate Limits

Our rate limits are implemented using a sliding window algorithm. This means:

  1. The per-second limit resets every second.
  2. The per-day limit is calculated on a rolling 24-hour basis, not on a fixed calendar day.

For example, if you make 10 requests at 10:00:00, you'll need to wait until at least 10:00:01 before making another request to avoid exceeding the per-second limit.

Handling Rate Limit Errors

If you exceed the rate limit, the API will return a 429 Too Many Requests HTTP status code. The response will include the following headers:

  • X-RateLimit-Limit: The rate limit period (e.g., "per_second" or "per_day")
  • X-RateLimit-Remaining: The number of requests left for the current rate limit window
  • X-RateLimit-Reset: The time at which the current rate limit window resets in UTC epoch seconds

Example response headers:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: per_second
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1623423980

When you receive a 429 response, you should wait until the time specified in X-RateLimit-Reset before making another request.

Increasing Rate Limits

The default rate limits are designed to accommodate most standard use cases. However, we understand that some integrations may require higher limits. Rate limit increases are considered on a case-by-case basis and are only granted when there is a demonstrated need.

To request an increase in your rate limits:

  1. Ensure you are efficiently using the existing rate limits (see Best Practices).
  2. Document your use case and the specific endpoints where you need increased limits.
  3. Calculate and provide an estimate of the number of requests you need per second and per day.
  4. Contact our support team at api-support@boyahq.com with the subject line "Rate Limit Increase Request".

Please note that not all requests for increased rate limits will be approved. We will evaluate each request based on its merits and the potential impact on our API's performance and stability.

Best Practices

To make the most of your rate limits and reduce the likelihood of hitting them:

  1. Cache responses: Store API responses locally when possible to reduce the number of API calls.
  2. Use bulk endpoints: Where available, use endpoints that allow you to fetch or update multiple resources in a single request.
  3. Implement retries with exponential backoff: When you hit a rate limit, wait before retrying, and increase the wait time for subsequent retries.
  4. Distribute requests evenly: Instead of sending requests in large bursts, try to distribute them evenly over time.
  5. Optimize your code: Ensure your integration is efficient and not making unnecessary API calls.

Monitoring Your Usage

To help you stay within the rate limits, we provide usage statistics in the Boya Admin Dashboard. To access these:

  1. Log in to the Boya Admin Dashboard.
  2. Navigate to the "API Usage" section.
  3. Here you can view your current usage, including:
    • Requests made per second (average and peak)
    • Total requests made per day
    • A breakdown of requests by endpoint

Regularly monitoring your usage can help you identify potential optimizations and anticipate when you might need to request a rate limit increase.

Remember, our rate limits are in place to ensure a stable and fair API for all users. By following these guidelines and best practices, you can create efficient integrations that work well within these limits.

Previous page