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

> Entenda os limites de requisições e como lidar com respostas 429

# Rate Limiting

A Business API aplica limites de requisições por merchant para garantir uso justo e estabilidade da plataforma.

## Headers de Resposta

Cada resposta inclui headers de rate limit que indicam sua cota atual:

| Header | Descrição |
| - | - |
| `X-RateLimit-Limit` | Máximo de requisições permitidas na janela atual |
| `X-RateLimit-Remaining` | Requisições restantes na janela atual |
| `X-RateLimit-Reset` | Timestamp Unix quando a janela reinicia |

Consulte esses headers em cada resposta para conhecer seu limite e quantas requisições restam.

## Lidando com 429 Too Many Requests

Quando você excede o limite, a API responde com status `429` e adiciona um header `Retry-After`:

```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"
}
```

## Estratégia de Retry

Use backoff exponencial quando receber uma resposta 429:

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

## Boas Práticas

* **Monitore o header `X-RateLimit-Remaining`** para reduzir a velocidade proativamente antes de atingir o limite.
* **Faça cache das respostas** quando os dados não mudam frequentemente — especialmente catálogos de produtos.
* **Agrupe seu trabalho** — solicite páginas maiores (até `limit=100`) para reduzir o número de requisições.
* **Respeite o `Retry-After`** — sempre espere o tempo indicado antes de tentar novamente, em vez de usar um delay fixo.


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