Skip to main content
A Chargefy limita o ritmo de chamadas de cada chave de API. O limite protege o checkout e a API de todas as organizações quando uma integração entra em laço ou faz uma varredura grande de uma vez. Consultas e criações têm cotas separadas, e uma cota curta de 10 segundos segura rajadas.

​
Limites por chave

  • A contagem é por chave de API. Duas chaves da mesma organização têm cotas independentes.
  • No Chargefy for Platforms, chamadas da chave de plataforma com o header Organization usam a cota de plataforma, somando todas as organizações conectadas.
  • Não contam: as páginas hospedadas (checkout, fatura, portal do cliente e ativação), as chamadas do Chargefy.js no navegador do comprador e o MCP, que tem limites próprios.
  • 120 criações por minuto equivalem a 7.200 pagamentos por hora numa única chave.

​
Ao passar do limite

A chamada volta 429 com o tipo rate_limit_error e o header Retry-After, em segundos. Ela não chega a ser processada: nada é criado nem alterado.
A mensagem diz qual cota acabou: read requests (consultas), write requests (criações e alterações) ou requests in a short burst (rajada de 10 segundos). O primeiro 429 de cada chave em cada minuto aparece nos registros de requisições.

​
Como tratar o 429

  • Espere o tempo de Retry-After antes de repetir. Somando um pequeno atraso aleatório, chamadas paradas ao mesmo tempo não voltam juntas.
  • Ao repetir uma criação ou alteração, envie o mesmo Idempotency-Key: a operação roda uma única vez.
  • Em lote, distribua no tempo. Importar 500 cupons leva cerca de 5 minutos a 120 por minuto, em vez de esbarrar no limite no primeiro minuto.

​
Aguarde o Pix pelo webhook

Para saber quando um Pix foi pago, cadastre um endpoint de webhook e processe payment.intent.succeeded. O evento sai assim que o pagamento é confirmado, sem nenhuma consulta da sua integração. Consultar o pagamento em laço gasta a cota de consultas sem trazer a informação antes. Uma tela que pergunta “já foi pago?” a cada 2 segundos faz 30 consultas por minuto por comprador; com quatro compradores pagando ao mesmo tempo, a chave chega ao limite. Se não houver como receber webhook, consulte no máximo a cada 10 segundos, aumente o intervalo a cada tentativa e pare no expires_at do código Pix. Veja o fluxo completo em Criar um pagamento.

​
Sincronize por período, não item por item

Para trazer para o seu sistema o que mudou num período, use a listagem com filtro de data e limit=100, e não uma consulta por ID. Sincronizar 300 transações do dia leva 3 chamadas assim, contra 300 consultas individuais.
Para as páginas seguintes, envie o ID do último item em starting_after. Veja Paginação.