Rate Limits

​

Q: How is my rate limit calculated?

• One budget across the whole API. All your API requests share a single limit for your environment, whichever endpoints they call. Each endpoint does not have its own limit.
• Default: 500 requests per minute. If you need more, contact support and we can raise it for your environment.
• Rolling window. We count requests over a sliding one-minute window, not a fixed bucket that resets at the start of each minute. A burst just before and just after the minute boundary doesn’t give you two minutes’ worth of requests.
• Dashboard use is separate. Your team using the Heron dashboard does not count against your API limit.
• Some endpoints have a stricter limit of their own.

​

Q: How do I know when I’m close to the limit?

​

Q: We are receiving 429 “Too Many Requests” errors. How should we handle them?

{
	"code": 429,
	"description": "500 per 1 minute",
	"name": "Too Many Requests"
}

1. Wait for the number of seconds in the Retry-After header, then retry.
2. If you get another 429, back off exponentially (for example 1s, 2s, 4s, 8s, with random jitter added). Never wait less than Retry-After.
3. Cap the number of retries, and log any requests you give up on.

import random
import time

import requests


def request_with_retry(method: str, url: str, max_retries: int = 5, **kwargs) -> requests.Response:
    for attempt in range(max_retries + 1):
        response = requests.request(method, url, **kwargs)
        if response.status_code != 429 or attempt == max_retries:
            return response
        retry_after = int(response.headers.get("Retry-After", 1))
        backoff = 2**attempt + random.random()
        time.sleep(max(retry_after, backoff))
    return response