Configure retry policy

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

Audience: public
Auth: API key
Permission: validations:update

Activates or modifies the automatic retry policy for a validation with a not_found, cep_unavailable or error outcome (v1.46.3, ADR-0074 D1). Does not apply to validations from bulk imports (D35) or to those already resolved / exhausted / outside the age window. Accepts optional Idempotency-Key to prevent duplicate retry dispatches on network retries. Validations with an active retry cycle can be listed via GET /v1/validations?retry_state=pending; the full retry_state (attempts consumed, next attempt, terminal state) is exposed by GET /v1/validations/{id}.

Parameters
Parameter	In	Type	Required	Description
`id` *	path	`string (uuid)`	required	Validation UUID.
`Idempotency-Key`	header	`string`	optional	Optional client-generated key (Stripe-style) that guarantees the request is processed exactly once within a 24-hour TTL. The scope is `(user_id, endpoint, key)`. Retries with the same key and the same body return the byte-for-byte cached response with the `Idempotent-Replayed: true` header, without consuming rate-limit quota, without re-firing webhooks, and without creating a new `validations` row. Same key with a different body → 422 `idempotency_key_reused`. Same key with an in-flight request → 409 `idempotency_key_in_progress`. 5xx responses are not cached (retries with the same key are processed for real). Format: 1–255 characters, alphanumeric + `_` + `-`.

Parameters
Parameter	Type	Required	Description
`retry_policy`	object	required	Automatic retry policy. Configures when and how many times the system retries a validation that returned an eligible outcome (`not_found`, `cep_unavailable` or `error` by default).

Request

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"
      ]
    }
  }'

Python example — coming soon.

JavaScript example — coming soon.

PHP example — coming soon.

**Response 200** `UpdateValidationRetryPolicyAttributes` — Retry policy activated. Returns the full current state of the retry cycle.
Field	Type	Description
`retry_state`	`object`	Full retry cycle state, included in the individual validation response (`GET /v1/validations/{id}`). Exposes both state fields and the configured policy details.
`enabled`	`boolean`	Whether the retry cycle is active for this validation.
`max_retries`	`integer \| null` nullable	Configured maximum number of retries. The upper bound depends on the plan (`retry_max_retries`) or the global default `max_retries_cap` (typically 5–10). `null` if `enabled=false`.
`interval_seconds`	`integer \| null` nullable	Interval between retries in seconds (300–86400). `null` if `enabled=false`.
`outcomes`	`array \| null` nullable	Validation outcomes that trigger a retry (`not_found`, `cep_unavailable`, `error`). `null` if `enabled=false`.
`attempts_completed`	`integer`	Number of retries completed so far.
`next_attempt_at`	`union`	Timestamp of the next scheduled retry. `null` if the cycle is in a terminal state or if no retries are active.
`resolved_at`	`union`	Timestamp when a retry resolved the validation to `valid`. `null` if the cycle has not ended by resolution.
`exhausted_at`	`union`	Timestamp when retries were exhausted without resolution. `null` if the cycle has not ended by exhaustion.
`cancelled_at`	`union`	Timestamp when the cycle was explicitly cancelled. `null` if not cancelled.
`terminal_state`	`string \| null` nullable	Terminal state of the cycle: `pending` — active, no final result yet; `resolved` — a retry obtained `valid`; `exhausted` — all attempts used; `cancelled` — cancelled by the user.

**Response status codes** `PUT /v1/validations/{id}/retry-policy`
Status	Class	Description	Body
200	`2xx`	Retry policy activated. Returns the full current state of the retry cycle.	No body
401	`4xx`	Authentication is required or the provided credentials are invalid.	`ErrorResponse`
403	`4xx`	Permisos insuficientes	`ErrorResponse`
404	`4xx`	Validation not found or not owned by the user (`not_found`).	`ErrorResponse`
422	`4xx`	Invalid policy or precondition not met. Codes: - `retry_policy_invalid`: shape / range / outcome not allowed. - `retry_not_supported_for_bulk`: validation came from an import (D35). - `retry_not_applicable`: status outside the allowlist (`not_found, cep_unavailable, error`) or concurrent state change. - `retry_already_resolved`: retry cycle already closed. - `retry_age_exceeded`: validation older than `max_age_seconds`. - `retry_pending_cap_exceeded`: per-user pending or 24h dispatched cap reached. - `reactivation_cap_exceeded`: per-validation reactivation cap exceeded (v1.46.3, H6).	`ErrorResponse`

**Response headers** `200`
Header	Type	Description
`Idempotent-Replayed`	`string`	Only present when the client sent `Idempotency-Key`. `true` when the response is a replay from the idempotency cache (24h TTL per user+endpoint+key).

**Errors from `PUT /v1/validations/{id}/retry-policy`**
Status	Code	Detail
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`

Retry policy

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

Automatic retry policy. Configures when and how many times the system retries a validation that returned an eligible outcome (`not_found`, `cep_unavailable` or `error` by default).

Attempts: —
Interval: 5 min – 1 h × 24
Eligible outcomes: not_found , cep_unavailable , error

This operation accepts an optional retry policy.