Cancelar reintentos pendientes

POST https://api.veriko.mx/v1/validations/{id}/cancel-retries

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

Cancela el ciclo de reintentos activo para una validación. La primera llamada retorna 200 con terminal_state: 'cancelled'; llamadas subsecuentes (sin ciclo activo) retornan 422 (retry_not_active). Acepta Idempotency-Key opcional para evitar dobles cancelaciones por reintentos de red.

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 + `_` + `-`.

Petición

cURLPython•JavaScript•PHP•

curl -X POST 'https://api.veriko.mx/v1/validations/{id}/cancel-retries' \
  -H 'Authorization: Bearer mxcep_••••' \
  -H 'Content-Type: application/json'

Ejemplo en Python — próximamente.

Ejemplo en JavaScript — próximamente.

Ejemplo en PHP — próximamente.

**Respuesta 200** `CancelValidationRetriesAttributes` — Ciclo de reintentos cancelado. `retry_state.terminal_state` queda `cancelled`.
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** `POST /v1/validations/{id}/cancel-retries`
Código	Clase	Descripción	Cuerpo
200	`2xx`	Ciclo de reintentos cancelado. `retry_state.terminal_state` queda `cancelled`.	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`	No hay ciclo de reintentos activo que cancelar (código `retry_not_active`). UUID inválido (`invalid_uuid`).	`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 `POST /v1/validations/{id}/cancel-retries`**
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`