Configurar política de reintentos

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

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

Activa o modifica la política de reintentos automáticos para una validación con resultado not_found, cep_unavailable o error. No aplica a validaciones parte de un import masivo ni a validaciones ya resueltas, agotadas o fuera de la ventana de edad permitida. Acepta Idempotency-Key opcional para evitar despachos duplicados de reintento ante reintentos de red. Las validaciones con ciclo activo se pueden listar vía GET /v1/validations?retry_state=pending; el retry_state completo (intentos consumidos, próximo intento, estado terminal) se observa en GET /v1/validations/{id}.

Parámetros
Parámetro	Ubicación	Tipo	Obligatorio	Descripción
`id` *	path	`string (uuid)`	obligatorio	UUID de la validación
`Idempotency-Key`	header	`string`	opcional	Llave opcional generada por el cliente (estilo Stripe) que garantiza que la petición se procese exactamente una vez dentro de un TTL de 24 horas. El alcance es `(user_id, endpoint, llave)`. Los reintentos con la misma llave y el mismo cuerpo devuelven la respuesta cacheada byte a byte con la cabecera `Idempotent-Replayed: true`, sin consumir cuota de rate-limit, sin re-disparar webhooks y sin crear una nueva fila en `validations`. Misma llave con cuerpo distinto → 422 `idempotency_key_reused`. Misma llave con una petición en vuelo → 409 `idempotency_key_in_progress`. Las respuestas 5xx no se cachean (los reintentos con la misma llave procesan de verdad). Formato: 1–255 caracteres, alfanuméricos + `_` + `-`.

Parámetros
Parámetro	Tipo	Obligatorio	Descripción
`retry_policy`	object	obligatorio	Política de reintentos automáticos. Configura cuándo y cuántas veces el sistema reintenta una validación cuyo resultado es elegible (`not_found`, `cep_unavailable` o `error` por defecto).

Petición

cURLPython•JavaScript•PHP•

curl -X PUT 'https://api.veriko.mx/v1/validations/{id}/retry-policy' \
  -H 'Authorization: Bearer mxcep_••••' \
  -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, incluido en la respuesta de una validación individual (`GET /v1/validations/{id}`). Expone tanto los campos de estado como los detalles de la política configurada.
`enabled`	`boolean`	Indica si el ciclo de reintentos está activo para esta validación.
`max_retries`	`integer \| null` anulable	Número máximo de reintentos configurado. El tope superior depende del plan (`retry_max_retries`) o del default global `max_retries_cap` (típicamente 5–10). `null` si `enabled=false`.
`interval_seconds`	`integer \| null` anulable	Intervalo entre reintentos en segundos (300–86400). `null` si `enabled=false`.
`outcomes`	`array \| null` anulable	Resultados de validación que habilitan un reintento (`not_found`, `cep_unavailable`, `error`). `null` si `enabled=false`.
`attempts_completed`	`integer`	Número de reintentos completados hasta el momento.
`next_attempt_at`	`union`	Timestamp del próximo reintento programado. `null` si el ciclo está en estado terminal o si no hay reintentos activos.
`resolved_at`	`union`	Timestamp cuando un reintento resolvió la validación a `valid`. `null` si el ciclo no ha terminado por resolución.
`exhausted_at`	`union`	Timestamp cuando se agotaron los reintentos sin resolución. `null` si el ciclo no ha terminado por agotamiento.
`cancelled_at`	`union`	Timestamp cuando el ciclo fue cancelado explícitamente. `null` si no fue cancelado.
`terminal_state`	`string \| null` anulable	Estado terminal del ciclo: `pending` — activo, sin resultado final aún; `resolved` — un reintento obtuvo `valid`; `exhausted` — se agotaron los intentos; `cancelled` — cancelado por el usuario.

**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.	Sin cuerpo
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 no pertenece al usuario (`not_found`).	`ErrorResponse`
422	`4xx`	Política inválida o precondición no cumplida. Códigos: - `retry_policy_invalid`: shape / rango / outcome no permitido. - `retry_not_supported_for_bulk`: la validación nació de un import (D35). - `retry_not_applicable`: status fuera del allowlist (`not_found, cep_unavailable, error`) o cambio de estado concurrente. - `retry_already_resolved`: el ciclo de reintentos ya cerró. - `retry_age_exceeded`: la validación es más vieja que `max_age_seconds`. - `retry_pending_cap_exceeded`: cap por usuario de pendientes O de dispatched-en-24h alcanzado. - `reactivation_cap_exceeded`: cap por validación de reactivaciones excedido (v1.46.3, H6).	`ErrorResponse`

**Cabeceras de respuesta** `200`
Cabecera	Tipo	Descripción
`Idempotent-Replayed`	`string`	Solo presente cuando el cliente envió `Idempotency-Key`. `true` cuando la respuesta es replay del caché de idempotencia (TTL 24h por usuario+endpoint+key).

**Errores de `PUT /v1/validations/{id}/retry-policy`**
Código	Clave	Detalle
401	`unauthorized`	Invalid or missing authentication credentials. Envelope meta.request_id `c4d5e6f7a8b9`
403	`forbidden`	You do not have permission to access this resource. Envelope meta.request_id `d5e6f7a8b9c0`

Política de reintentos

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

Política de reintentos automáticos. Configura cuándo y cuántas veces el sistema reintenta una validación cuyo resultado es elegible (`not_found`, `cep_unavailable` o `error` por defecto).

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

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