Rate limit em Pagamento de contas

Resumo

Este artigo descreve as regras de rate limit (limite de requisições) aplicadas à API de Pagamento de Contas da Celcoin. O rate limit controla o número de chamadas que cada conta cliente pode fazer em um intervalo de tempo e existe tanto em formato geral (cota de chamadas por conta) quanto em formato específico por título (linha digitável ou código de barras). O conteúdo é destinado a clientes Celcoin que integram com a API de Pagamento de Contas e precisam entender por que receberam um erro HTTP 429 ou HTTP 403, quanto tempo precisam aguardar e como evitar novos bloqueios.

Tipos de rate limit aplicados na API de Pagamento de Contas

A API de Pagamento de Contas da Celcoin aplica dois tipos distintos de rate limit, que funcionam de forma independente. Atingir um deles não desbloqueia o outro, e cada um retorna um código de erro HTTP diferente.

Limite geral de requisições por conta

A API de Pagamento de Contas da Celcoin define uma cota máxima de chamadas que cada conta cliente pode fazer em um intervalo de tempo específico. Esse limite considera o conjunto de requisições da conta à API de Pagamento de Contas, não apenas consultas a um título específico.

Quando esse limite geral é ultrapassado, novas tentativas são bloqueadas temporariamente e a API de Pagamento de Contas retorna o código HTTP 429. Após o tempo determinado de bloqueio, a conta volta a operar normalmente, sem necessidade de ação manual.

Os valores numéricos exatos da cota geral (número de chamadas por minuto/hora) não são publicados neste artigo. Para o detalhamento técnico vigente, consultar a documentação oficial em documentação.

Limite específico de consultas por título

Independentemente do limite geral, a API de Pagamento de Contas da Celcoin aplica um segundo controle por título: um mesmo título (identificado por sua linha digitável ou código de barras) pode ser consultado no máximo 20 vezes sequenciais.

Quando esse limite de 20 consultas para o mesmo título é ultrapassado, a API de Pagamento de Contas retorna o código HTTP 403 para novas consultas desse mesmo título. O cliente precisa aguardar até o próximo dia útil para realizar novas consultas para aquele título específico. Consultas a outros títulos continuam funcionando normalmente, desde que o limite geral também esteja respeitado.