Rate limiting
Para garantir a disponibilidade e a performance da API para todos, aplicamos um limite de requisições por chave de API (requisições sem chave contam por IP).
| Parâmetro | Tipo | Descrição |
|---|---|---|
/api/v1/* | limite | 120 requisições por minuto por chave de API (janela fixa de 60 segundos). |
Headers de resposta
Toda resposta da API inclui headers com o estado atual do seu limite:
| Parâmetro | Tipo | Descrição |
|---|---|---|
RateLimit-Limit | header | Limite máximo de requisições na janela. |
RateLimit-Remaining | header | Requisições restantes na janela atual. |
RateLimit-Reset | header | Unix timestamp (segundos) de quando a janela reseta. |
Ao exceder o limite
Você recebe 429 Too Many Requests com o header Retry-After indicando quantos segundos aguardar.
json
{
"data": null,
"error": "Rate limit excedido. Aguarde a janela resetar antes de novas requisições."
}Boas práticas
- Prefira webhooks a polling, você não gasta requisições esperando um pagamento cair.
- Implemente backoff exponencial com jitter ao receber
429. - Monitore
RateLimit-Remaininge desacelere antes de bater no teto. - Cacheie respostas que mudam pouco (ex.:
/v1/store) em vez de consultar a cada operação.