Configurar política de reintentos

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

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

Activa o modifica los reintentos automáticos de una validación que terminó en not_found, cep_unavailable o error. Existe porque esos tres veredictos no son necesariamente definitivos: el CEP puede tardar en publicarse. No todas las validaciones admiten reintentos. Quedan fuera las que forman parte de una importación masiva, las que ya se resolvieron, las que agotaron sus intentos y las que superan la antigüedad máxima que fija el plan. La cabecera Idempotency-Key es opcional y evita despachar dos veces el mismo reintento cuando un fallo de red repite la petición. Las validaciones con ciclo activo se listan con GET /v1/validations?retry_state=pending, y el estado completo —intentos consumidos, próximo intento, estado final— se ve en GET /v1/validations/{id}. Los topes y la progresión de los intentos están en la política de reintentos.

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 + `_` + `-`. p. ej. `11111111-2222-3333-4444-555555555555`

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 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, 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. p. ej. `true`
`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`. p. ej. `3`
`interval_seconds`	`integer \| null`anulable	Intervalo entre reintentos en segundos (300–86400). `null` si `enabled=false`. p. ej. `600`
`outcomes`	`array \| null`anulable	Resultados de validación que habilitan un reintento (`not_found`, `cep_unavailable`, `error`). `null` si `enabled=false`. p. ej. `["not_found","cep_unavailable","error"]`
`attempts_completed`	`integer`	Número de reintentos completados hasta el momento. p. ej. `1`
`next_attempt_at`	`TimestampUTC \| null`	Timestamp del próximo reintento programado. `null` si el ciclo está en estado terminal o si no hay reintentos activos.
`resolved_at`	`TimestampUTC \| null`	Timestamp cuando un reintento resolvió la validación a `valid`. `null` si el ciclo no ha terminado por resolución.
`exhausted_at`	`TimestampUTC \| null`	Timestamp cuando se agotaron los reintentos sin resolución. `null` si el ciclo no ha terminado por agotamiento.
`cancelled_at`	`TimestampUTC \| null`	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. `null` si la validación no tiene 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.	Sin cuerpo
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 no pertenece al usuario (`not_found`).	`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 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 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	Ejemplo
400	`body_empty`	El cuerpo de la petición está vacío. Envelope meta.request_id `c3d4e5f6a1b3`
400	`invalid_json`	El cuerpo no es JSON válido. Envelope meta.request_id `d4e5f6a1b2c4`
401	`unauthorized`	Credenciales de autenticación ausentes o inválidas. Envelope meta.request_id `c4d5e6f7a8b9`
403	`forbidden`	No tienes permiso para acceder a este recurso. Envelope meta.request_id `d5e6f7a8b9c0`
413	`body_too_large`	El cuerpo de la petición es demasiado grande. Envelope meta.request_id `1a2b3c4d5e6f`

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.