Compreender os Rate Limits
Este guia explica os limites de taxa da IZI Pay. Para garantir que o nosso Payment Gateway (https://pay.izipay.ao/) se mantem rapido, fiavel e justo para todos, aplicamos alguns limites de velocidade amigaveis aos pedidos de API.
Sempre que faz pedidos, contabilizamo-los em janelas de um minuto. Se enviar demasiados pedidos num único minuto, a nossa API ira pedir-lhe para abrandar, devolvendo um erro HTTP 429 Too Many Requests.
Precisa de um limite maior? Os limites descritos abaixo são pontos de partida padrão. Se o seu negócio está a crescer e atinge naturalmente estes limites durante as operações diarias, queremos ajudar! Basta contactar o Suporte IZI e podemos discutir o ajuste das quotas da sua conta de comerciante.
Como os Limites São Aplicados
Pense nos seus limites como uma quota personalizada. A quota está associada ao seu perfil de Comerciante / Tenant com base no seu token de autenticação. Isto significa que os seus limites são apenas seus e não são partilhados com outras empresas!
Limites de Velocidade por Operação
Diferentes tipos de pedidos de API exigem diferentes niveis de processamento. Para manter tudo a funcionar sem problemas, categorizamos os pedidos em tres grupos:
1. Escritas Mais Pesadas (Alterações de Estado)
- Limite: ~100 pedidos por minuto
- O que abrange: Ações que criam ou alteram dados de forma permanente (principalmente pedidos
POST). - Exemplos: Criar um novo pagamento, gerar referências PPR, emitir reembolsos ou cancelar uma autorização.
- Endpoints:
POST /api/payments,POST /api/payments/{id}/cancel,POST /api/references/ppr/bulk, etc.
2. Leitura e Sincronizacao (Obter Dados)
- Limite: ~500 pedidos por minuto
- O que abrange: Ações mais leves em que apenas solicita informação ou sincroniza estados (
GETe alguns pedidosPOST). - Exemplos: Verificar o estado de um pagamento, listar reembolsos anteriores ou consultar um histórico PPR.
- Endpoints:
GET /api/payments,GET /api/payments/{id},POST /api/payments/{id}/sync.
3. Terminais Fisicos (POS)
- Limite: ~1000 pedidos por minuto
- O que abrange: Terminais físicos em loja exigem polling muito rapido e de alto volume. Estes têm a sua propria via dedicada de alta velocidade!
- Exemplos: Abrir, fechar ou verificar o estado de um terminal físico.
Se um endpoint se enquadrar em duas categorias, aplicamos sempre o limite mais rigoroso (mais baixo) para garantir a estábilidade da plataforma.
O Que Fazer se Receber um Erro 429
Atingir um limite de velocidade pode acontecer. Se receber um erro HTTP 429, estás são as melhores práticas para o tratar sem problemas:
- Respire fundo (abrande): Procure o cabeçalho
Retry-Afterna nossa resposta. Ele indica exatamente quantos segundos deve aguardar antes de tentar novamente. - Use Exponential Backoff: Ao repetir um pedido que falhou, espere um pouco mais depois de cada tentativa (por exemplo, 1s, 2s, 4s, 8s). Isto evita que o seu sistema sobrecarregue acidentalmente o nosso.
- Tenha cuidado com pedidos POST: Se um pedido
GETfalhar, repeti-lo é inofensivo. Mas se um pedidoPOST(como criar um pagamento) receber um 429, não o repita cegamente! Pode acabar por cobrar um cliente duas vezes. Use sempre Order IDs ou References únicos para sabermos que é uma repetição e não uma nova transação. - Otimize o seu código: Se está a consultar o estado de um pagamento a cada 100 milissegundos, considere abrandar para a cada 2 segundos. Ou use endpoints em lote se precisar de criar vários PPRs de uma só vez!