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

# Rate limits

> Stay within the API-client budget and recover from HTTP 429 responses.

## Plan your request budget

| Credential | Budget | Shared across |
| - | - | - |
| API key | **500 requests per minute per key** | API routes called with that key |
| OAuth access token | **500 requests per minute per OAuth client and workspace** | Users and tokens for the same client and workspace |

Reads and writes share the budget. Each HTTP request counts once, including a bulk request. Browser sessions are outside this API-client limiter.

Coordinate concurrent workers that share a budget. Use [employee pagination](https://help.gowindmill.com/api-reference/pagination.md) to reduce requests, and spread work across the minute instead of sending a burst. For example, a single worker sending five requests per second leaves room in a 500/minute budget, provided other workers don't consume the remaining capacity.

## Read response headers

The API-client limiter uses these headers. Header names are case-insensitive; these values are illustrative:

```http theme={null}
RateLimit: limit=500, remaining=499, reset=60
RateLimit-Policy: 500;w=60
```

* `limit` is the request budget for the window.
* `remaining` is the number of requests left in that budget.
* `reset` is the number of **seconds** until the window resets, not a Unix timestamp.
* `w=60` is the policy window in **seconds**.

Read these values dynamically. On a limited request, `remaining` is `0` and the server adds `Retry-After`, a delay in seconds:

```http theme={null}
HTTP/1.1 429 Too Many Requests
RateLimit: limit=500, remaining=0, reset=12
RateLimit-Policy: 500;w=60
Retry-After: 12
```

The response uses the [standard API v2 error envelope](https://help.gowindmill.com/api-reference/errors.md) with `error.code: "RATE_LIMITED"`.

## Handle a 429

Wait at least `Retry-After` seconds before retrying. This Python example uses the standard library to make an employee search and retries a `429` up to three times:

```python theme={null}
import json
import os
import random
import time
from urllib.error import HTTPError
from urllib.request import Request, urlopen

url = (
    f"{os.environ['WINDMILL_API_BASE']}/c/"
    f"{os.environ['WINDMILL_COMPANY_ID']}/employees/search"
)
body = json.dumps({"page": 1, "pageSize": 100}).encode()
headers = {
    "Authorization": f"Bearer {os.environ['WINDMILL_API_KEY']}",
    "Content-Type": "application/json",
}

for attempt in range(4):
    try:
        with urlopen(Request(url, data=body, headers=headers), timeout=30) as response:
            result = json.load(response)
        break
    except HTTPError as error:
        if error.code != 429 or attempt == 3:
            raise
        delay = int(error.headers.get("Retry-After", "60"))
        error.close()
        time.sleep(max(0, delay) + random.uniform(0, 1))
```

Use the [environment variables from Making requests](https://help.gowindmill.com/api-reference/making-requests.md#read-employee-profiles). After a retry succeeds, pace subsequent requests and coordinate other workers; immediately sending another burst can exhaust the next window. Retry decisions for writes also need the [write-safety checks](https://help.gowindmill.com/api-reference/errors.md#retry-safely).


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