Política de reintentos
Una validación puede terminar sin veredicto por causas ajenas a los datos enviados: Banxico no responde, o el CEP todavía no está publicado. La política de reintentos vuelve a intentarlo automáticamente, sin que el cliente tenga que reenviar la petición.
El reintento no consume cuota adicional: pertenece a la validación original.
Qué desenlaces se reintentan
| desenlace | se reintenta |
|---|---|
not_found | Sí. El CEP puede publicarse más tarde |
cep_unavailable | Sí. Banxico identificó la operación pero aún no entregó el comprobante |
error | Sí. Fallo durante el procesamiento, como una consulta que Banxico no respondió |
valid | No. Hay veredicto |
invalid | No. Banxico respondió de una forma que el servicio no reconoce, y el ciclo de reintentos no lo atiende |
failed | No. Los datos enviados fueron rechazados, y repetirlos no lo cambia |
returned | No. El dinero ya se movió y volvió; repetir la consulta no lo cambia |
La distinción es si repetir la consulta puede dar un resultado distinto. Un dato mal formado no se arregla insistiendo.
Topes
| tope | valor por defecto |
|---|---|
| Reintentos por validación | 5 |
| Intervalo mínimo entre intentos | 5 minutos |
| Intervalo máximo | 24 horas |
| Antigüedad máxima de la validación | 7 días |
| Validaciones con reintento pendiente por cuenta | 50 |
| Reintentos despachados por día y cuenta | 200 |
| Reactivaciones de una misma validación | 3 |
Los valores de la tabla son los que se aplican por defecto. Tres de ellos los fija cada plan: los reintentos por validación, las validaciones con reintento pendiente por cuenta y los reintentos despachados por día y cuenta. El tope vigente de una cuenta es el de su plan activo, y se lee en meta.caps de GET /v1/users/me/retry-policy con los campos max_retries_cap, max_pending_per_user y max_dispatched_per_day_per_user.
Los topes por cuenta protegen frente a una acumulación que retrasaría los reintentos de todas las validaciones. Alcanzado el tope de pendientes o el de despachados por día, las validaciones nuevas que usan la política de la cuenta se procesan sin reintento automático; una petición con su propia retry_policy responde 422 retry_pending_cap_exceeded.
Configuración
La política tiene tres niveles. retry_policy en el cuerpo de POST /v1/validate o POST /v1/validate-ocr prevalece sobre la de la cuenta. El valor por omisión de la cuenta se consulta y modifica en GET/PUT /v1/users/me/retry-policy, y se aplica a las validaciones nuevas cuyo cuerpo no la trae. Una validación concreta se ajusta con PUT /v1/validations/{id}/retry-policy, que prevalece sobre el valor de la cuenta.
Estado en la validación
Toda validación expone retry_state, incluso cuando no tiene reintentos activos: en ese caso enabled es false y los campos de política son null. Las filas procedentes de una importación masiva llevan siempre enabled: false.
Cada transición del ciclo emite su evento de webhook —validation.retry.scheduled, validation.retry.resolved y validation.retry.exhausted—, de modo que el seguimiento no requiere sondear. La entrega de esos eventos se describe en la arquitectura de webhooks.