PUThttps://api.veriko.mx/v1/validations/{id}/retry-policy

Configurar política de reintentos

Audiencia: public
Autenticación: API key
Permiso: validations:read

Activa una política de reintentos automáticos para una validación con veredicto not_found, cep_unavailable o error.

Este tipo de veredictos pueden aparecer cuando la operación aún NO es procesada por Banxico, de tal modo que el sistema puede re-validar la transferencia en automático tras un periodo de tiempo establecido.

Un ciclo de reintentos puede devolver terminal_state="exhausted" cuando se alcanzan el máximo de reintentos configurado. También puede devolver terminal_state="cancelled" cuando el usuario cancela manualmente los reintentos de la validación.

En ambos casos, el ciclo puede reactivarse hasta tres veces; pasado ese tope, la petición se rechaza con 422 reactivation_cap_exceeded.

El estado completo de una validación se obtiene con GET /v1/validations/{id}, y los límites están descritos en la política de reintentos.

Parámetros
Parámetro	Ubicación	Tipo	Obligatorio	Descripción
`id`*	path	`string (uuid)`	obligatorio	Identificador (UUID) de la validación
`Idempotency-Key`	header	`string`	opcional	Llave opcional que garantiza que la petición se procese exactamente una vez dentro de un TTL de 24 horas. Los reintentos con la misma llave y el mismo cuerpo devuelven la respuesta cacheada con la cabecera `Idempotent-Replayed: true` (sin re-disparar webhooks) y sin crear una nueva validación. p. ej. `11111111-2222-3333-4444-555555555555`

Parámetros
Parámetro	Tipo	Obligatorio	Descripción
`retry_policy`	object	obligatorio	Política de reintentos de una validación: activación, límite, intervalo y resultados elegibles.
`enabled`	boolean	opcional	`true` cuando el ciclo de reintentos está activo. Si es `false`, los demás campos pueden ser ignorados. p. ej. `true`
`max_retries`	integer (≥ 1)	opcional	Número máximo de reintentos automáticos. Una vez alcanzado, el ciclo pasa al estado terminal `exhausted`. p. ej. `3`
`interval_seconds`	integer (≥ 300, ≤ 86400)	opcional	Segundos de espera entre cada reintento. Valores válidos: 300–86400 (5 min a 24h). p. ej. `600`
`outcomes`	array<string> (elementos: 1–?, elementos únicos)	opcional	Resultados que originan un reintento. De forma predeterminada son `not_found`, `cep_unavailable` y `error`; la combinación `["not_found", "cep_unavailable"]` excluye `error`. p. ej. `["not_found","cep_unavailable","error"]`

Petición

cURLPython•JavaScript•PHP•

curl -X PUT 'https://api.veriko.mx/v1/validations/{id}/retry-policy' \
  -H 'Authorization: Bearer veriko_••••' \
  -H 'Content-Type: application/json' \
  -d '{
    "retry_policy": {
      "enabled": true,
      "max_retries": 3,
      "interval_seconds": 600,
      "outcomes": [
        "not_found",
        "cep_unavailable"
      ]
    }
  }'

Ejemplo en Python — próximamente.

Ejemplo en JavaScript — próximamente.

Ejemplo en PHP — próximamente.

**Respuesta 200**`UpdateValidationRetryPolicyAttributes` — Política de reintentos activada. Devuelve el estado actual completo del ciclo.
Campo	Tipo	Descripción
`retry_state`	`object`	Estado completo del ciclo de reintentos, con configuración, avance y situación actual.
`enabled`	`boolean`	`true` cuando la validación tiene reintentos configurados, aunque su ciclo ya haya terminado (`terminal_state`). p. ej. `true`
`max_retries`	`integer \| null`anulable	Número máximo de reintentos configurado; `null` cuando `enabled` es `false`. p. ej. `3`
`interval_seconds`	`integer \| null`anulable	Intervalo en segundos entre reintentos, de `300` a `86400`; `null` cuando `enabled` es `false`. p. ej. `600`
`outcomes`	`array \| null`anulable	Resultados que originan un reintento: `not_found`, `cep_unavailable` y `error`; `null` cuando `enabled` es `false`. p. ej. `["not_found","cep_unavailable","error"]`
`attempts_completed`	`integer`	Cantidad de reintentos completados hasta el momento. p. ej. `1`
`next_attempt_at`	`TimestampUTC \| null`	Fecha del próximo reintento; `null` cuando no hay uno programado.
`resolved_at`	`TimestampUTC \| null`	Fecha en que un reintento obtuvo `valid`; `null` mientras no ocurra.
`exhausted_at`	`TimestampUTC \| null`	Fecha en que se agotaron los intentos; `null` mientras no ocurra.
`cancelled_at`	`TimestampUTC \| null`	Fecha de cancelación del ciclo; `null` mientras no ocurra.
`terminal_state`	`string \| null`anulable	Situación del ciclo: `pending`, `resolved`, `exhausted` o `cancelled`. Es `null` cuando la validación no tiene un ciclo de reintentos. p. ej. `pending`

**Códigos de respuesta**`PUT /v1/validations/{id}/retry-policy`
Código	Clase	Descripción	Cuerpo
200	`2xx`	Política de reintentos activada. Devuelve el estado actual completo del ciclo.	`UpdateValidationRetryPolicyAttributes`
400	`4xx`	El cuerpo de la petición está vacío o no es JSON válido.	`ErrorResponse`
401	`4xx`	Se requiere autenticación o las credenciales son inválidas	`ErrorResponse`
403	`4xx`	Permisos insuficientes	`ErrorResponse`
404	`4xx`	Validación no encontrada o ajena a la cuenta de usuario (`not_found`).	`ErrorResponse`
410	`4xx`	La validación se purgó y este recurso ya no existe (`validation_purged`).	`ErrorResponse`
413	`4xx`	El cuerpo de la petición supera el tamaño máximo admitido (`body_too_large`).	`ErrorResponse`
422	`4xx`	Política inválida o precondición no cumplida. `retry_policy_invalid`, la forma, el rango o el resultado no se admiten; `retry_not_supported_for_bulk`, la validación nació de una importación; `retry_not_applicable`, su estado queda fuera de los tres que admiten reintento (`not_found`, `cep_unavailable`, `error`) o cambió mientras tanto; `retry_already_resolved`, el ciclo ya cerró; `retry_age_exceeded`, la validación es más vieja que `max_age_seconds`; `retry_pending_cap_exceeded`, se alcanzó el tope de pendientes de la cuenta de usuario o el de despachados en 24 horas; `reactivation_cap_exceeded`, se alcanzó el tope de reactivaciones de esa validación.	`ErrorResponse`

**Cabeceras de respuesta**`200`
Cabecera	Tipo	Descripción
`Idempotent-Replayed`	`string`	Solo está presente cuando la petición incluyó `Idempotency-Key`. `true` indica que la respuesta se reutilizó desde el caché de idempotencia, cuya vigencia es de 24 horas por cuenta, endpoint y clave.

**Errores de `PUT /v1/validations/{id}/retry-policy`**
Código	Clave	Ejemplo
400	`body_empty`	El cuerpo de la petición está vacío. Envelope meta.request_id `c3d4e5f6a1b33b1a6f5e4d3c`
400	`invalid_json`	El cuerpo no es JSON válido. Envelope meta.request_id `d4e5f6a1b2c44c2b1a6f5e4d`
401	`unauthorized`	Credenciales de autenticación ausentes o inválidas. Envelope meta.request_id `c4d5e6f7a8b99b8a7f6e5d4c`
403	`permission_denied`	No tienes permiso para acceder a este recurso. Envelope meta.request_id `d5e6f7a8b9c00c9b8a7f6e5d`
410	`validation_purged`	La validación se purgó y este recurso ya no existe. Envelope meta.request_id `1a2b3c4d5e6ff6e5d4c3b2a1`
413	`body_too_large`	El cuerpo de la petición es demasiado grande. Envelope meta.request_id `1a2b3c4d5e6ff6e5d4c3b2a1`

Política de reintentos

PUT /v1/validations/{id}/retry-policy

Política de reintentos de una validación: activación, límite, intervalo y resultados elegibles.

Intentos: —
Intervalo: 5 min – 1 h × 24
Resultados elegibles: not_found, cep_unavailable, error

Esta operación admite una política de reintentos opcional.