Skip to main content
The Honeycomb API enforces rate limits to keep the platform stable and responsive for all users. Most API responses include headers that tell you where you stand in your current window, so you can monitor usage proactively and handle limits gracefully.

​
Rate Limit Headers

Most API responses include these headers:
HeaderDescription
RateLimitCurrent window status: limit=X, remaining=Y, reset=Z. X is the maximum requests allowed in the window, Y is the requests remaining, and Z is the number of seconds until the limit resets.
RateLimit-PolicyWindow policy: X;w=Y. X is the maximum requests per window, and Y is the window size in seconds.
Example: Rate Limit Header
RateLimit: limit=100, remaining=80, reset=54
RateLimit-Policy: 100;w=60
In this example, your rate limit policy allows 100 requests per 60-second window.In the current window, you have used 20 requests and have 80 remaining, with the window resetting in 54 seconds.
Not all endpoints return RateLimit and RateLimit-Policy headers. Each endpoint’s reference page indicates which headers are included in its responses.

​
Handling Rate Limit Errors

When you exceed the rate limit, the API returns a 429 Too Many Requests response. Honeycomb uses two response body formats depending on the API version.
V1 endpoints return an RFC7807 Problem Detail format:
{
"status": 429,
"type": "https://api.honeycomb.io/problems/rate-limited",
"title": "You have exceeded your rate limit.",
"error": "You have exceeded your rate limit.",
"detail": "Please try again after 2025-02-01T15:23:12Z."
}
Most 429 responses also include a Retry-After header with a timestamp indicating when you can retry: 
Retry-After: Fri, 22 Mar 2024 18:37:53 GMT
The Events, Batch Events, and Query Data APIs do not include a Retry-After header in their 429 responses.

​
Endpoint-Specific Rate Limits

Some endpoints have stricter limits in addition to the general API rate limit:
  • Create Query Result: Limited to 10 requests per minute.
  • Create Query Result with Relational Fields: Limited to 1 request per minute.

​
Best Practices

  • Check RateLimit: remaining in your response headers before making additional requests, especially in automated workflows or scripts.
  • When you receive a 429, implement exponential backoff rather than retrying immediately. Exponential backoff reduces pressure on the API and increases the likelihood that your retry succeeds.
  • Use the Retry-After timestamp to determine when to retry, rather than guessing or using a fixed delay.