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

export const FormField = ({property, label, required = false, diType, uiPatterns, children}) => {
  const patterns = Array.isArray(uiPatterns) ? uiPatterns : uiPatterns ? [uiPatterns] : [];
  return <div style={{
    margin: '1.5rem 0'
  }}>
      <div style={{
    display: 'flex',
    alignItems: 'baseline',
    flexWrap: 'wrap',
    gap: '0.5rem',
    marginBottom: '0.25rem'
  }}>
        <strong>{label}</strong>
        <span style={{
    fontSize: '0.7rem',
    fontWeight: 600,
    textTransform: 'uppercase',
    letterSpacing: '0.04em',
    color: required ? '#6241f5' : '#6b7280'
  }}>
          {required ? 'Required' : 'Optional'}
        </span>
      </div>

      <div>{children}</div>

      {diType || patterns.length > 0 ? <p style={{
    fontSize: '0.85rem',
    color: '#6b7280',
    marginBottom: 0
  }}>
          {diType ? <>
              See the <a href={`/references/${diType}`}>{diType}</a> reference.{' '}
            </> : null}
          {patterns.length > 0 ? <>
              Accepts a <a href={`/documentation/placeholders-and-patterns/patterns#${patterns[0]}`}>pattern</a>.
            </> : null}
        </p> : null}
    </div>;
};

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

<FormField property="remainingHeader" label="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.
</FormField>

<FormField property="threshold" label="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.
</FormField>

<FormField property="sleep" label="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.
</FormField>

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