Establecer política de reintentos por defecto

PUT https://api.veriko.mx/v1/users/me/retry-policy

Audiencia: public
Autenticación: API key

Configura la política de reintentos por defecto del usuario autenticado. Una vez guardada, se aplica a todas las validaciones futuras que no especifiquen una retry_policy en su body. La validación es estricta (no se clampa silenciosamente — supera los caps y rechaza). Acepta Idempotency-Key opcional para evitar reescrituras duplicadas ante reintentos de red.

Parámetros
Parámetro	Ubicación	Tipo	Obligatorio	Descripció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/users/me/retry-policy' \
  -H 'Authorization: Bearer mxcep_••••' \
  -H 'Content-Type: application/json' \
  -d '{
    "retry_policy": {
      "enabled": false
    }
  }'

Ejemplo en Python — próximamente.

Ejemplo en JavaScript — próximamente.

Ejemplo en PHP — próximamente.

**Respuesta 200** `RetryPolicy` — Política de reintentos por defecto del usuario.
Campo	Tipo	Descripción
`enabled`	`boolean`	Activa o desactiva el ciclo de reintentos para esta validación. Si es `false`, los demás campos se ignoran.
`max_retries`	`integer`	Número máximo de reintentos automáticos. Una vez alcanzado, el ciclo pasa al estado terminal `exhausted`. El tope superior depende del plan (`retry_max_retries`) o del default global `max_retries_cap` (típicamente 5–10).
`interval_seconds`	`integer`	Segundos de espera entre cada reintento (300–86400, es decir, 5 minutos a 24 horas).
`outcomes`	`array` (elementos: 1–?, elementos únicos)	Resultados de validación que habilitan un reintento. Por defecto el ciclo se activa con `not_found`, `cep_unavailable` y `error`; los clientes que no quieran reintentar errores Banxico HTTP 5xx pueden enviar `["not_found", "cep_unavailable"]`.

**Códigos de respuesta** `PUT /v1/users/me/retry-policy`
Código	Clase	Descripción	Cuerpo
200	`2xx`	Política de reintentos actualizada (eco del body normalizado).	Sin cuerpo
401	`4xx`	Se requiere autenticación o las credenciales son inválidas	`ErrorResponse`
422	`4xx`	La política de reintentos es inválida (`retry_policy_invalid`). Causas: campo `enabled` falta o no es booleano; `max_retries` fuera de `[1, max_retries_cap]`; `interval_seconds` fuera de `[min_interval_seconds, max_interval_seconds]`; `outcomes` vacío cuando `enabled=true`; outcome fuera del allowlist (`eligible_outcomes` de config/validation_retries.php).	`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/users/me/retry-policy`**
Código	Clave	Detalle
401	`unauthorized`	Invalid or missing authentication credentials. Envelope meta.request_id `c4d5e6f7a8b9`

Política de reintentos

PUT /v1/users/me/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.