O que é e como lidar com o Rate Limit no Pix?

O Rate Limit é um mecanismo de segurança que limita a quantidade de requisições que sua aplicação pode enviar para as APIs da Celcoin em um determinado intervalo de tempo. No ecossistema Pix, esse controle garante que o sistema permaneça estável para todos os usuários, evitando sobrecargas.

Como identificar que você atingiu o limite?

Quando o volume de chamadas excede o limite configurado para sua conta, a API retornará o código o erro "Atingiu o limite de requisições em um espaço curto de tempo durante a chamada da api. Tente novamente, mais tarde". Caso o balde de fichas do participante esteja esgotado devido a um volume elevado de consultas sem pagamento, novas consultas serão bloqueadas e o DICT retornará esse erro de rate limit.

O Manual Operacional do Banco Central estabelece que a limitação de requisições (rate limit) utiliza o algoritmo de Token Bucket (Balde de Fichas). Este mecanismo controla a quantidade de consultas de chaves que não resultam em uma ordem de pagamento imediata.

• Como funciona: Cada consulta consome uma "ficha". Se o volume de consultas sem pagamento associado for elevado, o balde se esgota e o DICT retorna erro de rate limit.

• Reposição de Fichas: Para que uma ficha seja reposta, o DICT espera que seja utilizado o identificador End-to-End (E2E) gerado em um pagamento efetivo.

• Dica: Realize a consulta da chave apenas no momento da transação ou em uma única validação imediatamente anterior à requisição de pagamento.

Validações Internas e Segurança

Como Instituição Financeira (IF), a Celcoin implementa camadas de validação interna para monitorar comportamentos que possam gerar notificações ou sanções junto ao Banco Central. Bloqueios preventivos podem ocorrer caso o padrão de uso do cliente apresente riscos à conformidade regulatória.
 

Diferenças entre Ambientes:

• Sandbox (Homologação): Possui limites mais restritos, voltados para testes de integração.

• Produção: Os limites são dimensionados de acordo com o volume de transações previsto em seu contrato.

Dica Técnica: Se a sua operação cresceu e você está atingindo o Rate Limit constantemente, mesmo com o uso de Webhooks e código otimizado, entre em contato com seu Gerente de Contas para solicitar um ajuste de quota.