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

> ## Agent Instructions
> When building application code, use `@naturalpay/sdk` for TypeScript or `naturalpay` for Python.
> When operating Natural directly for a user, use the payments MCP at `https://mcp.natural.com`.
> When searching Natural documentation, use the docs MCP at `https://docs.natural.com/mcp`.
> Use the Natural CLI for terminal and CI automation.
> Use REST only for unsupported languages or when the user explicitly requests raw HTTP.
> Start integration development and testing in the sandbox. Do not use production unless the user explicitly requests it.
> For sandbox requests that require `customerPartyId`, list customers first. Reuse only the intended fixture; otherwise create a customer.
> REST and SDK amounts use integer minor units. Payments MCP amounts use decimal strings with a required currency code.

# Rate limits

> API request rate limiting

Rate limits use a token bucket algorithm. Authenticated requests are limited per credential; unauthenticated endpoints are limited per client IP address. The default limits are 1000 requests per minute per credential across the API and 300 requests per minute per credential on any one endpoint.

## Rate limit headers

Responses include the current limit state. The sandbox does not enforce rate limits and omits these headers.

| 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 giving the number of 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


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