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

# Limites de requisição

> 120 por minuto no geral, 10 por hora em saque. E como não bater neles.

## Os limites

| Escopo                         | Limite          | Janela                                    |
| ------------------------------ | --------------- | ----------------------------------------- |
| Todas as rotas `/v1/*`         | 120 requisições | 60 segundos                               |
| `POST /v1/payouts`             | 10 saques       | 1 hora, por chave                         |
| `POST /v1/payouts` com `turbo` | 5 saques        | 1 hora, por chave, dentro do limite acima |

O limite geral é somado entre todos os endpoints. Não existe cota separada por recurso.

## Headers

Toda resposta traz os headers padrão, então dá pra desacelerar antes de bater no teto:

| Header                | Conteúdo                        |
| --------------------- | ------------------------------- |
| `RateLimit-Limit`     | Total permitido na janela       |
| `RateLimit-Remaining` | Quanto ainda resta              |
| `RateLimit-Reset`     | Segundos até a janela reiniciar |

## Quando estoura

```
HTTP/1.1 429 Too Many Requests
RateLimit-Limit: 120
RateLimit-Remaining: 0
RateLimit-Reset: 42

{ "error": "Rate limit exceeded. Max 120 requests/minute." }
```

<Warning>
  Não faça retry imediato de um `429`. Você continua bloqueado até a janela virar, e cada
  tentativa só empurra o problema pra frente.
</Warning>

Espere pelo menos o `RateLimit-Reset`, e use backoff exponencial com jitter:

```js theme={null}
async function comRetry(fn, maxTentativas = 5) {
  for (let i = 0; i <= maxTentativas; i++) {
    const res = await fn();
    if (res.status !== 429) return res;

    const reset = Number(res.headers.get("RateLimit-Reset")) || 2 ** i;
    const jitter = Math.random() * 1000;
    await new Promise((r) => setTimeout(r, reset * 1000 + jitter));
  }
  throw new Error("rate limit: máximo de tentativas excedido");
}
```

O jitter não é enfeite: sem ele, todos os seus workers acordam no mesmo instante e batem
no limite de novo, juntos.

## O jeito de não chegar perto

<CardGroup cols={2}>
  <Card title="Use webhook em vez de polling" icon="bell" href="/webhooks/visao-geral">
    É de longe a maior economia. Uma cobrança consultada a cada 3 segundos por 30 minutos
    são 600 requisições. O webhook resolve em uma.
  </Card>

  <Card title="Se precisar consultar, espace" icon="clock">
    Intervalo de 5 segundos ou mais, e pare no primeiro status final (`paid`, `expired`,
    `refunded`).
  </Card>

  <Card title="Pagine com limite alto" icon="list">
    As listagens aceitam `limit` até 100. Buscar de 10 em 10 gasta 10 vezes mais
    requisição pelo mesmo resultado.
  </Card>

  <Card title="Cacheie o que não muda" icon="database">
    Catálogo de produto não precisa ser relido a cada request do seu usuário.
  </Card>
</CardGroup>

<Tip>
  Se você tem vários serviços integrando, dê uma chave para cada um. Assim o limite de
  saque de um job não é consumido pelo checkout, e você descobre rápido qual serviço está
  gastando requisição à toa.
</Tip>