PIX 密钥查询（DICT）

DICT——Diretório de Identificadores de Contas Transacionais——是巴西央行 （BACEN）用于记录 PIX 密钥归属的目录。每当您询问「这个密钥属于谁」时，CorpX 都会代表 您向 DICT 发起查询。

这个询问是一种受配额管制的资源。BACEN 按机构计量 DICT 的消耗，而 CorpX 要为其所有 接入方的查询负责。一个大批量扫描密钥的客户，消耗的不只是自己的额度：它会拖累所有与我们 合作方的 DICT 访问，并让机构面临监管处罚。

正因如此，查询消耗会被实时计量、逐账户统计，并由 CorpX 持续监控。本页说明我们计量什么、 您能看到什么、我们对您的流量有何预期，以及当这一预期被打破时会发生什么。

接入密钥查询前请先阅读本页

滥用 DICT 不会被当作可以容忍的技术小问题。它会导致警告、收紧您的限额、暂停账户，若持续 不改，则终止您对本机构的访问权限。参见 警告、暂停与终止。

每一次查询都会被记录

每一次访问 DICT 都会在我们这边留下一条永久记录，包含发起查询的账户、查询来源、时间戳 以及结果——找到密钥、密钥不存在、被 DICT 拒绝，或技术故障。这些都不是抽样：它是完整 日志，您在门户中看到的数字和我们看到的数字都来自于它。

查询密钥有两种方式，两种都计入：

• 显式查询——GET /v1/accounts/{accountId}/pix/key/{pixKey}。
• KEY 模式的 PIX Out——POST /v1/accounts/{accountId}/pix/out、/async 和 /bigpix。资金转出前必须先解析密钥，而该询问同样发往 DICT。

按密钥付款目前尚未消耗额度

对 PIX Out 内部解析动作的计费正在灰度推进。目前它会被记录和计量，但尚未扣减您的 额度，也不会因此返回 429。正式启用前我们会提前通知。

计量的内容

有两类规则运行在这些记录之上，每次查询都会评估，以最严格的一项为准。

绝对计数：用了多少、有多快

限额	窗口	防止什么
maxLookupsPerDay	自然日（BRT）	总量超出约定
maxLookupsPerMinute	滚动 60 秒	突发：总量不超日限，却在瞬间涌入
maxNotFoundPer5min	滚动 5 分钟	枚举：盲扫会在日限触发前产生大量 NOT_FOUND

速率：您如何使用这些查询

计数类限额无法区分「为了付款而查询」和「为了收集而查询」。一个账户可以轻松地把每日查询 控制在 500 次以内，同时每笔 PIX 却花掉 40 次查询——这是扫描密钥的特征，而非付款的特征。 两个速率把这两种情况区分开：

速率	计量方式	揭示了什么
每笔支付的查询次数（maxUsageRatio）	窗口内 查询次数 ÷ 已完成 PIX Out 笔数	从未转化为支付的查询
失败率（maxFailureRatio）	窗口内（未找到 + 被拒绝）÷ 查询次数	对不存在密钥的扫描

两者都在十二个同时生效的时间窗口上计算——5m、15m、30m、1h、3h、6h、 12h、24h、3d、7d、14d 和 30d。短窗口抓突发；长窗口抓那种有耐心的滥用，即 摊薄在一天之中、不易察觉的那种。把扫描分散到一周并不管用：7 天窗口看得到整整一周。

每个窗口都有样本下限（minLookups）。低于该值时两个速率都不会拒绝，因为基于三次 调用算出的速率毫无意义。正是它让新账户能够安心完成最初的几次查询。

未声明数值的窗口不等于该窗口被关闭。 它会继承全平台基线，速率管理始终生效。当前 生效的数值、配置约定与默认值见 政策与规则。

一切都按账户计量

没有任何限额是按租户汇总的。一个账户的查询绝不会计入另一个账户，即便二者属于同一租户 ——包括在租户层级配置限额的情形，那只是一个逐账户套用的模板。之所以以账户为单位，是因为 突发发生在账户上，处罚也落在账户上。

什么不消耗额度

• 缓存命中。 对同一密钥的重复查询由 24 小时缓存提供，缓存命中不消耗额度。该缓存在 两条路径间共享：一次显式查询可以服务随后的付款，反之亦然。
• 我方或清算方的技术故障。 服务不可用不是您的责任，不会烧掉您的额度。
• 已被 429 拒绝的查询。 已经被拦下的一方，不会因为每次重试而陷得更深。

您看到的与我们看到的完全一致

在接入方门户中，**「PIX 查询额度」**页面展示的 正是驱动拒绝判定的那组数字。不存在隐藏的计量：如果门户显示您已用到上限的 60%，那么限额 引擎读到的就是这个值。

对于所选窗口，该页面会展示：

• 查询次数、已完成的 PIX Out、未解析出密钥的查询，以及被限额拒绝的查询——租户合计 以及按账户的同口径拆分。
• 每笔支付的查询次数与失败率，各自附带实测值、已消耗上限比例的进度条，以及当前 生效的上限。
• 每个账户在该窗口中的状态：在限额内、接近限额，或已超限。
• 点开某个账户后，十二个窗口并排展示，这正是判断问题属于偶发突发还是持续模式的地方。
• 最近 30 天被拒绝的查询列表，每个 429 一行。

关注这个页面，是您在被拦截之前及时纠偏的方式；而如果您的正当业务场景确实无法适配当前 规则，它也是您申请复核策略时所依据的材料。

当限额触发时

该查询会被拒绝，返回 429 与 errorCode: dict_lookup_limit_exceeded。消息中会说明 是哪条规则触发、测得多少、上限是多少：

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%

当多个窗口同时超限时，响应会引用最短的那个——它是直接原因，也是最先恢复的。

每次拒绝还会触发 policy.violation webhook，其 phase 为 "dict_lookup"，便于您 及时响应，而不必等人去看页面。

如何解除阻断

窗口是滑动的：随着时间推移、超出部分移出被测区间，它们会自行恢复。5 分钟窗口几分钟即可 恢复；30 天窗口则不然。

行不通的做法是继续硬试。被拒绝的查询不计入额度，但也不会加快恢复，而对着一个已经 关闭的限额连续重试，恰恰是会引向下文所述升级处置的行为模式。请把 429 当作停止信号： 停止发送流量，在页面上找出是哪个窗口触发，然后等待它恢复。

如果拒绝来自某个长窗口，而您的业务量确属正当，请联系支持，而不要试图绕开。

并非所有 429 都是您的额度

当清算方对 CorpX 的流量进行限流时，同一路由也会返回 429，但 errorCode 为 partner_rate_limited。那不是您的限额，您的任何计数器都没有触发。在断定额度耗尽之前， 请先检查 errorCode。

我们对您的流量有何预期

这里没有什么技巧：用 DICT 来付款的一方，离限额始终很远。这套规则是基于生产环境中真实 接入方的流量校准的，在该区间内没有拦下他们中的任何一个。

请这样做：

• 在您即将付款的时刻，查询您即将付款的那个密钥。
• 善用 24 小时缓存。重新展示一个已查询过的收款方无需再次访问 DICT，只有在归属可能已经 变更时，?noCache=true 才有正当理由。
• 询问前先校验密钥格式。格式错误的密钥等于一次被浪费的查询，还会抬高您的失败率。
• 把 429 当作停止信号并配合退避，同时监听 policy.violation webhook。
• 关注额度页面；在可预见业务增长时，在触顶之前申请策略复核。

请不要这样做：

• 遍历税号、手机号或邮箱区间来探测哪些密钥存在。这正是 NOT_FOUND 限额要抓的行为，也是 CorpX 容忍度最低的一种。
• 为了充实数据库、校验客户名单、在支付场景之外确认归属，或支撑您自有的查询类产品而调用 查询。DICT 不是户籍资料的数据源，这类用途受 PIX 监管规则禁止，而不仅仅是我们的政策 所禁止。
• 把同一批扫描分散到您租户下的多个账户以稀释计量。每个账户虽单独计量，但整个租户层面的 模式对我们是可见的，并会被作为同一种行为来评判。
• 对着已经触发的限额反复重试。

警告、暂停与终止

CorpX 会以跨租户、跨账户的视角持续复核全平台的 DICT 消耗。一旦出现滥用模式，处置会按比例 逐级升级：

1. 联系与警告。 我们会通过支持渠道与您沟通，附上支撑该判断的数据以及整改期限。
2. 收紧限额。 您的策略会被设置为严于基线的上限，范围可以是涉事账户，也可以是整个 租户。您仍可继续运营，只是余量更少。
3. 暂停账户。 由 CorpX 操作员执行人工且留痕的操作暂停该账户，并记录原因。在此期间， 该账户的所有路由都会返回 403 forbidden——不只是密钥查询。该租户下的其他账户不受 影响，照常运营。
4. 暂停或关停租户。 若持续不改或情节严重，该租户的访问会被暂停——返回 403 tenant_suspended，写操作被阻断、查询仍然可用——或被彻底停用，返回 403 tenant_disabled。

这些步骤并非必须逐级执行的固定流程。蓄意扫描密钥、把 DICT 当作户籍数据源使用，以及试图 绕开计量的行为，会跳过前面的步骤，因为它们会立即让机构暴露于风险之中。

任何一种情形下，恢复都不是自动的：需经由支持渠道处理，取决于根因是否已被修复，并会连同 批准该操作的操作员一并记录在案。

这是对处置方式的说明，不能替代合同

本页描述该控制在实践中如何运作，以及运营团队会做什么。您与 CorpX 之间合同中的商业条款 与监管义务继续完全有效，如有冲突以合同为准。

延伸阅读

• 政策与规则——字段参考、默认值、账户与租户之间的 优先级，以及如何配置。
• 错误——完整错误目录，包括 dict_lookup_limit_exceeded 与 partner_rate_limited。
• Webhooks——policy.violation 的投递、重试与签名。
• 对您的业务场景有疑问：请通过支持渠道或 api@corpx.com 联系我们。接入前先问，比被拦下 之后再改要划算。