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

# Rate limits

> API request rate limiting

Rate limits use a token bucket algorithm. Authenticated requests are limited per API key; unauthenticated endpoints are limited per client IP address.

## Rate limit headers

Every response carries the current limit state:

| Header                  | Description                                    |
| ----------------------- | ---------------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests allowed in the current window |
| `X-RateLimit-Remaining` | Requests remaining in the current window       |
| `X-RateLimit-Reset`     | Unix epoch seconds when the window resets      |

A `429` response also includes a `Retry-After` header — seconds to wait before retrying.

## Rate limit response

When you exceed the rate limit, the API returns `429 Too Many Requests`:

```json theme={null}
{
  "errors": [
    {
      "code": "rate_limited",
      "detail": "Too many requests. Please try again later.",
      "status": "429",
      "meta": {
        "supportId": "req_a1b2c3d4e5f6"
      }
    }
  ]
}
```

## Handling rate limits

Back off and retry with exponential delay:

```python theme={null}
import asyncio
import httpx

async def request_with_backoff(client: httpx.AsyncClient, url: str, **kwargs):
    max_retries = 3
    for attempt in range(max_retries):
        response = await client.get(url, **kwargs)
        if response.status_code != 429:
            return response
        # Honor Retry-After when present, else fall back to exponential backoff.
        retry_after = response.headers.get("Retry-After")
        wait = int(retry_after) if retry_after else 2 ** attempt
        await asyncio.sleep(wait)
    return response
```

## Best practices

* **Batch where possible.** Fewer large requests beat many small ones.
* **Cache responses** that don't change frequently (e.g., party details, wallet balance).
* **Implement exponential backoff** on `429` responses.

## Related

* [Error Handling](/api-reference/errors/error-handling) — Error response format
* [Idempotency](/api-reference/idempotency) — Safe retries after rate limiting