Limites de uso

Para proteger a plataforma e a sua conta, a API limita a quantidade de chamadas por minuto. Os limites variam conforme o tipo de operação — consultas têm folga, operações que movimentam dinheiro são mais restritas.

Tipo de operação	Limite por chave (aprox.)
Consultas (GET de pagamentos, PIX…)	300 por minuto
Cadastros (clientes, etc.)	60 por minuto
Criação de cobrança (PIX/pagamento)	30 por minuto
Saques	10 por minuto
Relatórios	30 por minuto

Além do limite por chave, existem limites somados por lojista e por organização, então criar várias chaves não aumenta a sua cota. Os valores acima são os atuais e podem ser ajustados; trate os headers da resposta como fonte da verdade.

Headers

Respostas trazem o estado da sua cota:

Header	Significado
x-ratelimit-limit	Limite da janela atual.
x-ratelimit-remaining	Quantas chamadas ainda restam.
x-ratelimit-reset	Quando a janela reinicia.
x-request-id	Identificador da chamada — informe ao suporte.

Ao receber 429

A resposta é 429 RATE_LIMITED com o header Retry-After (segundos) e, no corpo, error.details.retry_after. Aguarde esse tempo antes de tentar de novo; insistir antes pode prolongar o bloqueio.

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Muitas requisições. Tente novamente em 30 segundos.",
    "details": { "retry_after": 30, "scope": "merchant", "policy": "api:withdrawal" }
  }
}

Se a proteção estiver momentaneamente indisponível, a API responde 503 RATE_LIMIT_UNAVAILABLE (operações financeiras são bloqueadas por segurança). Tente novamente em instantes.

Recomendações

• Prefira webhooks a ficar consultando status repetidamente.
• Use backoff exponencial com variação aleatória nas repetições.