Retry policy
A validation may end without a verdict for reasons unrelated to the submitted data: Banxico is unresponsive, or the CEP is not published yet. The retry policy attempts it again automatically, without the client having to resend the request.
A retry consumes no additional quota: it belongs to the original validation.
Which outcomes are retried
| outcome | retried |
|---|---|
not_found | Yes. The CEP may be published later |
cep_unavailable | Yes. Banxico identified the operation but has not delivered the receipt yet |
error | Yes. Failure during processing, such as a query Banxico did not answer |
valid | No. A verdict exists |
invalid | No. Banxico answered in a way the service does not recognize, and the retry cycle does not handle it |
failed | No. The submitted data was rejected, and repeating it changes nothing |
returned | No. The money already moved and came back; repeating the query does not change that |
The distinction is whether repeating the query can yield a different result. Malformed data is not fixed by insisting.
Caps
| cap | default value |
|---|---|
| Retries per validation | 5 |
| Minimum interval between attempts | 5 minutes |
| Maximum interval | 24 hours |
| Maximum age of the validation | 7 days |
| Validations with a pending retry per account | 50 |
| Retries dispatched per day per account | 200 |
| Reactivations of a single validation | 3 |
The values in the table are the defaults. Three of them are set by each plan: retries per validation, validations with a pending retry per account, and retries dispatched per day per account. The cap in force for an account is the one of its active plan, and it is read in meta.caps of GET /v1/users/me/retry-policy through the fields max_retries_cap, max_pending_per_user and max_dispatched_per_day_per_user.
The per-account caps guard against a backlog that would delay retries across all validations. Once the pending cap or the daily dispatched cap is reached, new validations that use the account policy are processed without automatic retry; a request with its own retry_policy answers 422 retry_pending_cap_exceeded.
Configuration
The policy has three levels. retry_policy in the body of POST /v1/validate or POST /v1/validate-ocr takes precedence over the account one. The account default is read and changed through GET/PUT /v1/users/me/retry-policy, and applies to new validations whose body does not carry one. An individual validation is adjusted with PUT /v1/validations/{id}/retry-policy, which takes precedence over the account value.
State on the validation
Every validation exposes retry_state, even when no retries are active: in that case enabled is false and the policy fields are null. Rows coming from a bulk import always carry enabled: false.
Each transition of the cycle emits its webhook event — validation.retry.scheduled, validation.retry.resolved and validation.retry.exhausted — so tracking requires no polling. Delivery of those events is described in the webhooks architecture.