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

# Rate limit based on header

> Check response headers for the request limit and wait for a set amount of time before resuming.

Slows the connection down before it runs into an API's rate limit. After each response, this plugin reads a header that tells it how many requests you have left. When that number drops to or below the threshold you set, it pauses for the number of seconds you choose before continuing. Use this with APIs that report a remaining request count, such as a `X-RateLimit-Remaining` header, so a long sync backs off on its own instead of being blocked with rate-limit errors.

This documentation describes: [Schema](/schemas/http-client-plugin-configurator/rate-limit-header)

## Fields

**Header in response that tells remaining requests**

Required

The name of the response header that reports how many requests you have left in the current window, for example `X-RateLimit-Remaining`. The plugin reads this header after every response. If the service does not send it, no pausing happens.

**Threshold to start sleeping**

Required

The remaining-requests count at which the connection should start pausing. When the value in the header drops to this number or lower, the plugin waits before sending the next request. Set it a little above zero to give yourself a safety margin.

**Time to sleep in seconds**

Required

How long to pause, in seconds, once the threshold is reached. Choose a value long enough for the rate-limit window to refresh, based on the API's documented limits.

## Sample data

This plugin pauses the connection based on response headers rather than transforming data, so there is no before/after to show. The example below watches `X-RateLimit-Remaining`, and whenever it reports 5 or fewer requests left, the connection waits 60 seconds before continuing.

| Field | Value |
| - | - |
| Header in response that tells remaining requests | `X-RateLimit-Remaining` |
| Threshold to start sleeping | `5` |
| Time to sleep in seconds | `60` |

```json Configuration theme={null}
{
  "prototype": "rate-limit-header",
  "parameters": {
    "remainingHeader": "X-RateLimit-Remaining",
    "threshold": 5,
    "sleep": 60
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.