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

# Limites de requisição

> 100 por minuto no geral, 20 por minuto em saque. E como não bater neles.

## Os limites

| Escopo | Limite | Janela |
| - | - | - |
| Todas as rotas `/v1/*` | 100 requisições | 60 segundos, por conta |
| `POST /v1/payments` | 100 cobranças | 60 segundos, por conta, dentro do limite acima |
| `POST /v1/withdrawals`, `POST /v1/subaccounts/{id}/withdrawals` e `POST /v1/refunds` | 20 no total | 60 segundos, por conta |
| `POST` e `PATCH` em `/v1/payment-links` | 60 | 1 hora, por conta |

O limite geral é somado entre todos os endpoints e todas as chaves da conta. Não existe cota separada por chave nem por recurso.

A janela é deslizante: em nenhum intervalo de 60 segundos passam mais pedidos que o limite, e o contador não zera de uma vez na virada do minuto. Cada pedido libera a vaga dele 60 segundos depois de feito.

## Headers

Toda resposta com chave de API 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é liberar a próxima vaga |

## Quando estoura

```http theme={null}
HTTP/1.1 429 Too Many Requests
Retry-After: 42
RateLimit-Limit: 100
RateLimit-Remaining: 0
RateLimit-Reset: 42

{ "error": { "code": "RATE_LIMITED", "message": "Muitas tentativas. Espere um pouco e tente de novo." } }
```

> [!WARNING]
>
> Não faça retry imediato de um 429. Você continua recusado até liberar uma vaga, e repetir em laço só gasta tempo do seu servidor.

Espere pelo menos o `Retry-After` (ele vale também nos limites de saque e de cobrança), 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 espera = Number(res.headers.get("Retry-After")) || 2 ** i;
    const jitter = Math.random() * 1000;
    await new Promise((r) => setTimeout(r, espera * 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. Ao repetir um `POST` de cobrança ou saque, mande a mesma `Idempotency-Key`: assim o retry nunca cria nada em dobro ([Convenções](https://docs.wyzecash.com.br/convencoes.md)).

## O jeito de não chegar perto

### Use webhook em vez de polling

É de longe a maior economia. Um Pix consultado a cada 3 segundos durante os 30 minutos de validade são 600 requisições. O [webhook](https://docs.wyzecash.com.br/webhooks/configurar.md) `payment.paid` resolve em uma.

### Se precisar consultar, espace

Intervalo de 5 segundos ou mais, e pare no primeiro status final (`paid`, `expired` ou `refunded`).

### Pagine com limite alto

As listagens aceitam `limit` até 100 e paginam por cursor. Buscar de 10 em 10 gasta 10 vezes mais requisição pelo mesmo resultado.

### Cacheie o que não muda

As formas de pagamento (`GET /v1/payments/methods`) e as tarifas da conta (`GET /v1/fees`) mudam pouco: leia uma vez e guarde por alguns minutos, em vez de consultar a cada pedido do seu cliente. O saldo, consulte quando for usar.

> [!TIP]
>
> Se você tem vários serviços integrando, dê uma chave para cada um. O limite é da conta, somado entre as chaves, mas assim você vê em Integrações e API qual chave foi usada por último e pode desligar só a do serviço que está gastando requisição à toa.


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