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

# Rate Limiting

> Understand rate limits and how to handle them.

Rate limits protect the API from abuse and ensure fair usage for all consumers.

## Limits

| Scope                                    | Limit            | Key         |
| ---------------------------------------- | ---------------- | ----------- |
| **Authenticated API** (`/v1/*`, `/v2/*`) | 100 requests/min | Per API key |

## Response When Limited

When you exceed a rate limit, the API returns:

* **HTTP 429** Too Many Requests
* **Error code**: `RATE_LIMIT_EXCEEDED`
* **`Retry-After` header**: number of seconds to wait before retrying

```json theme={null}
{
  "timestamp": "2026-03-24T12:00:00.000Z",
  "success": false,
  "message": "Too many requests. Please try again later.",
  "errorCode": "RATE_LIMIT_EXCEEDED",
  "type": "",
  "data": null
}
```

## Rate Limit Headers

Every response includes standard rate limit headers per the [IETF RateLimit header fields](https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/09/) specification:

| Header             | Description                                                                 | Example                                        |
| ------------------ | --------------------------------------------------------------------------- | ---------------------------------------------- |
| `ratelimit-policy` | Policy name, quota (`q`), window in seconds (`w`), and partition key (`pk`) | `"100-in-1min"; q=100; w=60; pk=:ZGE1M2Y4...:` |
| `ratelimit`        | Policy name, remaining requests (`r`), and seconds until reset (`t`)        | `"100-in-1min"; r=99; t=60`                    |
| `Retry-After`      | Seconds to wait before retrying (**only on 429 responses**)                 | `30`                                           |

## Best Practices

1. **Respect `Retry-After`** — when you receive a 429, wait for the specified number of seconds
2. **Monitor rate limit headers** — parse the `RateLimit` header to check remaining requests and throttle proactively
3. **Use exponential backoff** — if retrying, increase delay: 1s, 2s, 4s
4. **Cache results** — Human Design charts for the same birth data are deterministic. Cache responses to avoid redundant calls
5. **Batch wisely** — if generating multiple charts, space requests evenly rather than bursting