Cancelar reintentos pendientes

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

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

Detiene el ciclo de reintentos automáticos de una validación. La primera llamada responde 200 con terminal_state: 'cancelled'; una segunda, ya sin ciclo activo, responde 422 retry_not_active. Esa diferencia es deliberada: cancelar algo que no está corriendo no es una operación sin efecto, es una señal de que el estado no era el que se creía. La cabecera Idempotency-Key es opcional y evita que un fallo de red convierta una cancelación en dos.

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`

Petición

cURLPython•JavaScript•PHP•

curl -X POST 'https://api.veriko.mx/v1/validations/{id}/cancel-retries' \
  -H 'Authorization: Bearer veriko_••••' \
  -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. 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**`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	Ejemplo
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`