Existe limite de consultas DICT?

Resumo

As consultas de chaves no DICT (Diretório de Identificadores de Contas Transacionais) possuem limites obrigatórios definidos pelo Banco Central no Manual Operacional do DICT. O controle é feito por um sistema de baldes e fichas que opera em dois níveis independentes: um balde por parceiro Celcoin (controle da Celcoin sobre o tráfego do integrador) e um balde por usuário final identificado pelo payerId (controle do Banco Central por CPF ou CNPJ). Este artigo explica as regras de consumo, reposição e bloqueio em cada um dos dois níveis, e como interpretar o erro HTTP 429 retornado quando um balde se esgota.

Como funcionam os dois níveis de controle de consultas DICT

Sim, as consultas de chave Pix no DICT são limitadas em dois níveis simultâneos e independentes. Toda consulta consome fichas em ambos os baldes ao mesmo tempo; se qualquer um dos dois baldes ficar vazio, a consulta é recusada com erro HTTP 429.

Nível 1: balde do parceiro Celcoin

Cada parceiro Celcoin tem um balde próprio, cuja capacidade e taxa de reposição são definidas pela Celcoin com base no histórico de uso do parceiro. Este balde controla o tráfego agregado do parceiro contra o DICT.

Nível 2: balde do usuário final (payerId)

Cada usuário final em nome de quem o parceiro Celcoin faz consultas (identificado pelo payerId) tem um balde próprio, com capacidade e taxa de reposição definidas pelo Banco Central. Este balde controla o quanto cada CPF ou CNPJ pode consultar o DICT, somando todas as instituições por onde o usuário opera.

Regras explícitas — Balde do parceiro Celcoin

Capacidade e reposição:

• A capacidade do balde do parceiro Celcoin é definida pela Celcoin com base no histórico de uso do parceiro.
• A taxa fixa de reposição por minuto do balde do parceiro Celcoin é definida pela Celcoin com base no histórico de uso do parceiro.

O que CONSOME fichas do balde do parceiro Celcoin:

• Consulta de chave Pix bem-sucedida no DICT consome 1 ficha, independentemente de haver pagamento posterior.
• Consulta de chave Pix com erro HTTP 400 (Bad Request) consome, de forma definitiva, 3 fichas.
• Consulta de chave Pix com erro HTTP 404 (Not Found) consome, de forma definitiva, 3 fichas.
• Consultas sequenciais com erro (HTTP 400 ou HTTP 404) que ultrapassem 20 fichas consumidas no total ativam o mecanismo anti-scan: a partir desse ponto, cada nova consulta passa a consumir 20 fichas.

O que REPÕE fichas no balde do parceiro Celcoin:

• Pagamento Pix bem-sucedido (HTTP 200) realizado com o mesmo endToEndId de uma consulta anterior ao DICT repõe 1 ficha.
• Reposição automática à taxa fixa por minuto definida pela Celcoin para o parceiro.

O que acontece quando o balde do parceiro Celcoin se esgota:

• O parceiro Celcoin fica temporariamente impedido de consultar o DICT.
• A API retorna erro HTTP 429 (Too Many Requests) em novas tentativas.
• As consultas só são reiniciadas quando o balde voltar a ter fichas disponíveis (via reposição automática por minuto ou via pagamentos bem-sucedidos vinculados por endToEndId).

Regras explícitas — Balde do usuário final (controle do Banco Central)

Capacidade do balde do usuário final, por tipo de pessoa:

• Usuário Pessoa Física (identificado por CPF no payerId): 100 fichas.
• Usuário Pessoa Jurídica (identificado por CNPJ no payerId): 1.000 fichas.

Taxa de reposição automática do balde do usuário final:

• 5 fichas por minuto, para ambos os tipos de pessoa (PF e PJ).

O que CONSOME fichas do balde do usuário final:

• Consulta de chave Pix bem-sucedida no DICT consome 1 ficha do balde do usuário final que fez a consulta.
• Consulta de chave Pix com erro HTTP 404 consome, de forma definitiva, 20 fichas do balde do usuário final.

O que REPÕE fichas no balde do usuário final:

• Pagamento Pix bem-sucedido (HTTP 200) realizado com o mesmo endToEndId de uma consulta anterior ao DICT repõe 1 ficha no balde do usuário final.
• Reposição automática à taxa de 5 fichas por minuto.

O que acontece quando o balde do usuário final se esgota:

• O usuário final (payerId) fica temporariamente impedido de consultar chaves Pix no DICT, em qualquer instituição em que opere.
• A API retorna erro HTTP 429 (Too Many Requests) em novas tentativas para aquele payerId.
• As consultas para aquele payerId só são reiniciadas quando o balde do usuário final voltar a ter fichas disponíveis.

Quando todas as fichas de um balde forem usadas, o usuário (payerId) ficará temporariamente impedido de consultar chaves. A partir daí, será necessário esperar até que o balde esteja novamente positivo para que as consultas sejam reiniciadas.