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

# Rate Limiting

> Understand request limits and how to handle 429 responses

# Rate Limiting

The Business API enforces per-merchant rate limits to ensure fair usage and platform stability.

## Response Headers

Every response includes rate limit headers that tell you your current quota:

| 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 timestamp when the window resets |

Check these headers on every response to know your limit and how many requests you have left.

## Handling 429 Too Many Requests

When you exceed the limit, the API responds with status `429` and adds a `Retry-After` header:

```bash theme={null}
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 1
X-RateLimit-Limit: 1
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1710288000
```

```json theme={null}
{
  "type": "RateLimitExceededError",
  "detail": "Rate limit exceeded"
}
```

## Retry Strategy

Use exponential backoff when you receive a 429 response:

<CodeGroup>
  ```python Python theme={null}
  import time
  import httpx

  def request_with_retry(url: str, headers: dict, max_retries: int = 3):
      for attempt in range(max_retries):
          response = httpx.get(url, headers=headers)
          if response.status_code != 429:
              return response
          retry_after = int(response.headers.get("Retry-After", 2 ** attempt))
          time.sleep(retry_after)
      return response
  ```

  ```javascript Node.js theme={null}
  async function requestWithRetry(url, headers, maxRetries = 3) {
    for (let attempt = 0; attempt < maxRetries; attempt++) {
      const response = await fetch(url, { headers });
      if (response.status !== 429) return response;
      const retryAfter = parseInt(response.headers.get("Retry-After") || 2 ** attempt);
      await new Promise((r) => setTimeout(r, retryAfter * 1000));
    }
  }
  ```
</CodeGroup>

## Best Practices

* **Monitor the `X-RateLimit-Remaining` header** to proactively slow down before hitting the limit.
* **Cache responses** when the data doesn't change frequently — especially product catalogs.
* **Batch your work** — fetch larger pages (up to `limit=100`) to reduce the number of requests.
* **Respect `Retry-After`** — always wait the indicated time before retrying, rather than using a fixed delay.


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