> ## Documentation Index
> Fetch the complete documentation index at: https://docs.honeycomb.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate Limits

> Find out how Honeycomb API rate limits work, which response headers tell you your current usage, and how to handle 429 rate-limited errors.

export const CalloutExample = ({children}) => {
  return <Callout icon="clipboard-check" color="#6B7280">
      {children}
    </Callout>;
};

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:

| Header             | Description                                                                                                                                                                                        |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `RateLimit`        | Current 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-Policy` | Window policy: `X;w=Y`. `X` is the maximum requests per window, and `Y` is the window size in seconds.                                                                                             |

<CalloutExample>
  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.
</CalloutExample>

<Note>
  Not all endpoints return `RateLimit` and `RateLimit-Policy` headers.
  Each endpoint's reference page indicates which headers are included in its responses.
</Note>

## 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.

<Tabs>
  <Tab title="V1 Endpoints">
    V1 endpoints return an RFC7807 Problem Detail format:

    ```json theme={}
    {
    "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."
    }
    ```
  </Tab>

  <Tab title="V2 Endpoints">
    V2 endpoints return a JSON:API format:

    ```json theme={}
    {
    "errors": [
        {
        "id": "06dcdd6508ca822f0e7e2bb4121c1f52",
        "code": "rate-limited/may-retry",
        "title": "request rate limit exceeded",
        "detail": "Please try again after 2025-02-01T15:23:12Z."
        }
    ]
    }
    ```
  </Tab>
</Tabs>

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
```

<Note>
  The Events, Batch Events, and Query Data APIs do not include a `Retry-After` header in their `429` responses.
</Note>

## 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.