PIX key lookups (DICT)

DICT — Diretório de Identificadores de Contas Transacionais — is the BACEN registry that says who owns a PIX key. Every time you ask "whose key is this", CorpX asks DICT on your behalf.

That question is a rationed resource. BACEN meters DICT consumption per institution, and CorpX answers for everything its integrators look up. A client scanning keys in bulk does not only spend their own allowance: they degrade DICT access for everyone operating with us, and expose the institution to regulatory sanction.

That is why lookup consumption is measured in real time, account by account, and watched continuously by CorpX. This page describes what we measure, what you can see, what we expect of your traffic, and what happens when that expectation is broken.

Read this before integrating key lookups

DICT abuse is not treated as a technical nuisance to be tolerated. It leads to a warning, tighter limits on your account, account suspension and, if it persists, termination of your access to the institution. See Warning, suspension and termination.

Every lookup is recorded

Each trip to DICT becomes a permanent record on our side, with the account that asked, where the question came from, the timestamp and the outcome — key found, key not found, key refused by DICT, or technical failure. None of this is sampled: it is the complete log, and it feeds both the numbers you see in the portal and the ones we see.

There are two ways to look a key up, and both count:

• The explicit lookup — GET /v1/accounts/{accountId}/pix/key/{pixKey}.
• PIX Out in KEY mode — POST /v1/accounts/{accountId}/pix/out, /async and /bigpix. The key must be resolved before the money leaves, and that question goes to the same DICT.

Paying by key does not consume quota yet

Charging the resolution made inside a PIX Out is rolling out. Today it is recorded and measured, but it does not yet draw down your quota or produce a 429. We will announce it before turning it on.

What is measured

Two kinds of rule run over that record, evaluated on every lookup. The most restrictive one wins.

Absolute counts: how much and how fast

Limit	Window	What it prevents
maxLookupsPerDay	calendar day (BRT)	Total volume beyond what was agreed
maxLookupsPerMinute	rolling 60s	Bursts: fits the daily cap, but arrives all at once
maxNotFoundPer5min	rolling 5 min	Enumeration: blind scanning produces many NOT_FOUND before the daily cap closes

Rates: what use you make of the lookups

Count limits cannot tell apart someone looking up to pay from someone looking up to collect. An account can sit comfortably within 500 lookups a day and still spend 40 lookups per PIX — the profile of someone scanning keys, not paying. Two rates separate the cases:

Rate	What it measures	What it reveals
Lookups per payment (maxUsageRatio)	lookups ÷ completed PIX Outs in the window	Lookups that never become payments
Failure rate (maxFailureRatio)	(keys not found + refused) ÷ lookups in the window	Scanning for keys that do not exist

Both are computed over twelve simultaneous time windows — 5m, 15m, 30m, 1h, 3h, 6h, 12h, 24h, 3d, 7d, 14d and 30d. The short window catches the burst; the long one catches patient abuse, the kind that hides diluted across a day. Spreading a scan over a week does not help: the 7-day window sees the whole week.

Every window has a sample floor (minLookups). Below it neither rate can refuse, because a rate computed over three calls means nothing. That is what lets a new account make its first lookups in peace.

A window with no declared numbers is not a window turned off. It inherits the fleet baseline, and rate management is always on. The values in force, the configuration convention and the defaults are in Policies and Rules.

Everything is measured per account

No limit is aggregated per tenant. One account's lookups never count against another, even within the same tenant — including when the limit was configured at tenant level, which works as a template applied to each account individually. The account is the unit because that is where the burst happens and where the penalty lands.

What does not consume quota

• Cache hits. Repeat lookups of the same key are served from a 24h cache, and a cache hit costs nothing. The cache is shared between both paths: an explicit lookup serves the payment that follows, and vice versa.
• Technical failures, ours or the settlement provider's. Downtime is not your fault and does not burn quota.
• A lookup already refused with 429. Someone already blocked does not dig deeper with every retry.

You see exactly what we see

In the Integrator Portal, the PIX lookup bucket screen shows the same numbers that feed the decision to refuse. There is no hidden measurement: if the portal says you are at 60% of the cap, that is what the limit engine is reading.

For the selected window, the screen shows:

• Lookups, completed PIX Outs, lookups that resolved no key, and lookups refused by a limit — tenant totals and the same breakdown per account.
• Lookups per payment and failure rate, each with the measured value, a bar for how much of the cap is spent, and the cap in force.
• Each account's state in the window: within the limit, close to it, or over.
• All twelve windows side by side when you open an account, which is where you can tell a one-off burst from a sustained pattern.
• The list of refused lookups from the last 30 days, one row per 429.

Watching this screen is how you correct course before being blocked — and, if your legitimate use case does not fit the current rule, it is the material you use to request a review of your policy.

When a limit closes

The lookup is refused with 429 and errorCode: dict_lookup_limit_exceeded. The message says which rule closed, what was measured and what the cap was:

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%

When more than one window is over, the response cites the shortest one — it is the immediate cause and the first to clear.

Every refusal also fires the policy.violation webhook with phase: "dict_lookup", so you can react without waiting for someone to look at the screen.

How to get out of a block

The windows slide: they clear on their own as time passes and the excess falls out of the measured range. A 5-minute window clears in minutes; a 30-day one does not.

What does not work is insisting. A refused lookup is not charged, but it does not speed up the release either, and a burst of retries against an already-closed limit is exactly the pattern that leads to the escalation below. Treat 429 as a stop signal: halt the traffic, find on the screen which window closed, and wait for it to open.

If the refusal comes from a long window and your volume is legitimate, talk to support instead of trying to work around it.

Not every 429 is your quota

The same route returns 429 with errorCode: partner_rate_limited when the settlement provider throttles CorpX's traffic. That is not your limit and no counter of yours closed. Check the errorCode before concluding your quota ran out.

What we expect of your traffic

There is no trick to it: whoever uses DICT to pay stays far from the limits. The rule was calibrated against real traffic from integrators in production and blocked none of them.

Do:

• Look up the key you are about to pay, at the moment you are about to pay it.
• Use the 24h cache. Re-displaying a recipient you already looked up needs no new trip to DICT, and ?noCache=true is only justified when ownership may have changed.
• Validate the key format before asking. A malformed key is a wasted lookup and raises your failure rate.
• Treat 429 as a stop, with backoff, and monitor the policy.violation webhook.
• Watch the bucket screen and ask for a policy review before hitting the cap, when growth is expected.

Do not:

• Scan ranges of tax IDs, phone numbers or emails to discover which keys exist. That is the behaviour the NOT_FOUND limits exist to catch, and the one CorpX treats with the least tolerance.
• Look up keys to enrich a database, validate a customer base, confirm ownership outside a payment, or feed a lookup product of your own. DICT is not a source of registry data, and that use is barred by PIX regulation, not just by our policy.
• Spread the same scan across several accounts of your tenant to dilute the measurement. Each account is measured on its own, but the pattern across the tenant is visible to us and is judged as a single behaviour.
• Retry against a limit that has already closed.

Warning, suspension and termination

CorpX reviews DICT consumption across the whole fleet continuously, with a cross-tenant, cross-account view. When a pattern of abuse shows up, the response is proportional and escalates:

1. Contact and warning. We reach out through the support channel with the numbers behind the observation and a deadline to correct it.
2. Tighter limits. Your policy gets caps stricter than the baseline, on the offending account or on the whole tenant. You keep operating, with less room.
3. Account suspension. The account is suspended by a manual, audited action from a CorpX operator, with the reason on record. While it lasts, every route of that account returns 403 forbidden — not just key lookups. The tenant's other accounts keep operating.
4. Tenant suspension or shutdown. If it persists, or if the case is severe enough, the tenant's access is suspended — 403 tenant_suspended, with write operations blocked and reads still available — or disabled entirely, with 403 tenant_disabled.

These steps are not a mandatory script. Deliberate key scanning, using DICT as a source of registry data, and attempts to work around the measurement skip the early steps, because they expose the institution immediately.

Reactivation is never automatic: it goes through support, depends on the cause having been fixed, and is recorded along with the operator who authorised it.

A description of conduct, not a replacement for your contract

This page describes how the control works in practice and what the operation does. The commercial terms and regulatory obligations in your contract with CorpX remain fully in force and prevail in case of divergence.

Where to read more

• Policies and Rules — the field reference, defaults, precedence between account and tenant, and how to configure them.
• Errors — the full catalogue, including dict_lookup_limit_exceeded and partner_rate_limited.
• Webhooks — delivery, retries and signing of policy.violation.
• Questions about your use case: the support channel or api@corpx.com. Asking before you integrate costs less than fixing it after being blocked.