Consultas de chave PIX (DICT)

O DICT — Diretório de Identificadores de Contas Transacionais — é o cadastro do BACEN que diz a quem pertence uma chave PIX. Toda vez que você pergunta "de quem é esta chave", a CorpX pergunta ao DICT em seu nome.

Essa pergunta é um recurso racionado. O BACEN mede o consumo de DICT por instituição, e a CorpX responde por tudo o que os seus integradores consultam. Um cliente que varre chaves em massa não gasta só a própria cota: ele degrada o acesso ao DICT de todos os que operam conosco, e expõe a instituição a sanção do regulador.

Por isso o consumo de consulta é medido em tempo real, conta a conta, e é acompanhado pela CorpX de forma contínua. Esta página descreve o que medimos, o que você consegue ver, o que esperamos do seu tráfego e o que acontece quando essa expectativa é quebrada.

Leia isto antes de integrar a consulta de chave

Uso abusivo do DICT não é tratado como um problema técnico a ser tolerado. Ele resulta em advertência, aperto dos seus limites, suspensão da conta e, na persistência, encerramento do acesso à instituição. Ver Advertência, suspensão e desligamento.

Toda consulta é registrada

Cada ida ao DICT vira um registro nosso, permanente, com a conta que perguntou, a origem da pergunta, o horário e o desfecho — chave encontrada, chave inexistente, chave recusada pelo DICT ou falha técnica. Nada disso é amostragem: é o log completo, e é dele que saem tanto os números que você vê no painel quanto os que nós vemos.

São duas as formas de consultar, e as duas contam:

• A consulta explícita — GET /v1/accounts/{accountId}/pix/key/{pixKey}.
• O PIX Out no modo KEY — POST /v1/accounts/{accountId}/pix/out, /async e /bigpix. A chave precisa ser resolvida antes de o dinheiro sair, e essa pergunta vai para o mesmo DICT.

O pagamento por chave ainda não consome cota

A contagem da resolução feita dentro de um PIX Out está em implantação. Hoje ela é registrada e medida, mas ainda não desconta da sua cota nem gera 429. Avisaremos com antecedência antes de ligar.

O que é medido

Sobre esse registro correm dois tipos de régua, avaliados a cada consulta. Vale sempre a mais restritiva.

Contagem absoluta: quanto e quão rápido

Limite	Janela	O que evita
maxLookupsPerDay	dia-calendário (BRT)	Volume total além do contratado
maxLookupsPerMinute	60s rolantes	Rajada: cabe no teto diário, mas chega tudo de uma vez
maxNotFoundPer5min	5 min rolantes	Enumeração: varredura cega gera muito NOT_FOUND antes de o teto diário fechar

Taxa: que uso você faz das consultas

Os limites de contagem não distinguem quem consulta para pagar de quem consulta para colecionar. Uma conta pode caber folgado em 500 consultas por dia e ainda assim gastar 40 consultas por PIX — perfil de quem varre chave, não de quem paga. Duas taxas separam os dois casos:

Taxa	O que mede	O que revela
Consultas por pagamento (maxUsageRatio)	consultas ÷ PIX Out concluídos na janela	Consulta que não vira pagamento
Taxa de falha (maxFailureRatio)	(chaves inexistentes + recusadas) ÷ consultas na janela	Varredura de chaves que não existem

As duas são calculadas em doze janelas de tempo simultâneas — 5m, 15m, 30m, 1h, 3h, 6h, 12h, 24h, 3d, 7d, 14d e 30d. A janela curta pega a rajada; a longa pega o abuso paciente, aquele que se esconde diluído no dia. Não adianta espalhar a varredura ao longo da semana: a janela de 7 dias enxerga a semana inteira.

Cada janela tem um piso de amostra (minLookups). Abaixo dele nenhuma das duas taxas pode recusar, porque taxa calculada sobre três chamadas não significa nada. É o que permite a uma conta nova fazer suas primeiras consultas em paz.

Janela sem números declarados não é janela desligada. Ela herda a linha de base da frota, e a gestão de taxa está sempre ativa. Os valores em vigor, a convenção de configuração e os defaults estão em Políticas.

Tudo é medido por conta

Nenhum limite é agregado por tenant. As consultas de uma conta nunca entram na contagem de outra, mesmo dentro do mesmo tenant — inclusive quando o limite foi configurado no nível do tenant, que funciona como molde aplicado a cada conta individualmente. A conta é a unidade porque é nela que a rajada acontece e é nela que a punição chega.

O que não consome cota

• Cache hit. Consultas repetidas da mesma chave são servidas de um cache de 24h, e cache hit não gasta cota. O cache é compartilhado entre os dois caminhos: uma consulta explícita serve o pagamento seguinte, e vice-versa.
• Falha técnica nossa ou do liquidante. Indisponibilidade não é culpa sua e não queima cota.
• Consulta já recusada com 429. Quem já foi barrado não afunda mais fundo a cada nova tentativa.

Você vê exatamente o que nós vemos

No Portal do Integrador, a tela Balde de consultas PIX mostra os mesmos números que alimentam a decisão de recusar. Não há medição oculta: se o painel diz que você está em 60% do teto, é isso que o motor de limites está lendo.

A tela traz, para a janela escolhida:

• Consultas, PIX Out concluídos, consultas que não resolveram chave e consultas recusadas por limite — os totais do tenant e a mesma quebra por conta.
• Consultas por pagamento e taxa de falha, cada uma com o valor medido, uma barra de quanto do teto já foi consumido e o teto em vigor.
• O estado de cada conta na janela: dentro do limite, perto dele ou estourada.
• As doze janelas lado a lado ao abrir uma conta, que é onde se enxerga se o problema é uma rajada pontual ou um padrão sustentado.
• A lista de consultas recusadas dos últimos 30 dias, uma linha por 429.

Acompanhar essa tela é a forma de corrigir o rumo antes de ser barrado — e, se o seu caso de uso legítimo não couber na régua atual, é o material com o qual você pede uma revisão da sua policy.

Quando o limite fecha

A consulta é recusada com 429 e errorCode: dict_lookup_limit_exceeded. A mensagem diz qual regra fechou, o que foi medido e qual era o teto:

DICT lookup usage too high for this account in the last 1h:
120 lookups for 10 successful transfers (12.0 per transfer); max 6.0

DICT lookup failure rate too high for this account in the last 5m:
18 of 24 lookups did not resolve a key (75%); max 40%

Quando mais de uma janela está acima do teto, a resposta cita a mais curta — é a causa imediata e a primeira a liberar.

Toda recusa também dispara o webhook policy.violation com phase: "dict_lookup", para você reagir sem depender de alguém olhar a tela.

Como sair do bloqueio

As janelas são deslizantes: elas liberam sozinhas conforme o tempo passa e o excesso sai do intervalo medido. Uma janela de 5 minutos limpa em minutos; a de 30 dias, não.

O que não funciona é insistir. Consulta recusada não entra na conta, mas também não acelera a liberação, e uma rajada de tentativas contra um limite já fechado é exatamente o padrão que leva à escalada descrita abaixo. Trate o 429 como sinal de parada: interrompa o envio, descubra na tela qual janela fechou e espere ela abrir.

Se a recusa vier de uma janela longa e o seu volume for legítimo, fale com o suporte em vez de tentar contornar.

Nem todo 429 é a sua cota

A mesma rota responde 429 com errorCode: partner_rate_limited quando o liquidante limita o tráfego da CorpX. Não é limite seu e nenhum contador da sua conta fechou. Confira o errorCode antes de concluir que a cota acabou.

O que esperamos do seu tráfego

Não há truque aqui: quem usa o DICT para pagar passa longe dos limites. A régua foi calibrada sobre tráfego real de integradores em operação e não barrava nenhum deles.

Faça:

• Consulte a chave que você vai pagar, no momento em que vai pagar.
• Aproveite o cache de 24h. Reexibir um destinatário já consultado não precisa de nova ida ao DICT, e ?noCache=true só se justifica quando a titularidade pode ter mudado.
• Valide o formato da chave antes de perguntar. Chave malformada vira consulta desperdiçada e sobe a sua taxa de falha.
• Trate 429 como parada, com backoff, e monitore o webhook policy.violation.
• Acompanhe a tela de balde e peça revisão de policy antes de bater no teto, quando o crescimento é previsto.

Não faça:

• Varrer faixas de CPF, CNPJ, telefone ou e-mail para descobrir que chaves existem. É o comportamento que os limites de NOT_FOUND existem para pegar, e o que a CorpX trata com menos tolerância.
• Consultar para enriquecer cadastro, validar base de clientes, confirmar titularidade fora de um pagamento ou alimentar produto próprio de consulta. O DICT não é fonte de dados cadastrais, e esse uso é vedado pela regulação do PIX, não só pela nossa política.
• Distribuir a mesma varredura entre várias contas do seu tenant para diluir a medição. Cada conta é medida sozinha, mas o padrão no conjunto do tenant é visível para nós e é avaliado como um só comportamento.
• Repetir a chamada contra um limite já fechado.

Advertência, suspensão e desligamento

O consumo de DICT de toda a frota é revisado pela CorpX de forma contínua, com visão cruzada de todos os tenants e todas as contas. Quando um padrão de abuso aparece, a resposta é proporcional e escala:

1. Contato e advertência. Falamos com você pelo canal de suporte, com os números que sustentam a observação e o prazo para correção.
2. Aperto dos limites. Sua policy passa a ter tetos mais restritivos que a linha de base, na conta ofensiva ou no tenant inteiro. Você continua operando, com menos folga.
3. Suspensão da conta. A conta é suspensa por ação manual e auditada de um operador da CorpX, com motivo registrado. Enquanto durar, todas as rotas daquela conta respondem 403 forbidden — não só a consulta de chave. As demais contas do tenant seguem operando.
4. Suspensão ou desligamento do tenant. Na persistência ou na gravidade, o acesso do tenant é suspenso — 403 tenant_suspended, com as operações de escrita bloqueadas e as consultas ainda disponíveis — ou desativado por completo, com 403 tenant_disabled.

As etapas não são um roteiro obrigatório. Varredura deliberada de chaves, uso do DICT como fonte de dados cadastrais e tentativa de contornar a medição dispensam as etapas iniciais, porque expõem a instituição imediatamente.

Reativação não é automática em nenhum dos casos: passa pelo suporte, depende da causa ter sido corrigida e é registrada com o operador que a autorizou.

Descrição de conduta, não substituto do contrato

Esta página descreve como o controle funciona na prática e o que a operação faz. Os termos comerciais e as obrigações regulatórias do seu contrato com a CorpX continuam valendo integralmente e prevalecem em caso de divergência.

Onde ver mais

• Políticas — a referência dos campos, defaults, precedência entre conta e tenant, e como configurar.
• Erros — o catálogo completo, incluindo dict_lookup_limit_exceeded e partner_rate_limited.
• Webhooks — entrega, retentativa e assinatura do policy.violation.
• Dúvida sobre o seu caso de uso: canal de suporte ou api@corpx.com. Perguntar antes de integrar custa menos que corrigir depois de ser barrado.