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

Configure retry policy

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

Activates an automatic retry policy for a validation with a not_found, cep_unavailable or error verdict.

Verdicts of that kind can appear while the operation has NOT yet been processed by Banxico, so the system can re-validate the transfer automatically after a set period.

A retry cycle can return terminal_state="exhausted" when the configured maximum number of retries is reached. It can also return terminal_state="cancelled" when the user cancels the validation's retries manually.

In both cases the cycle can be reactivated up to three times; past that cap, the request is rejected with 422 reactivation_cap_exceeded.

The full state of a validation is obtained with GET /v1/validations/{id}, and the caps are described in the retry policy.

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

Parameters
Parameter	Type	Required	Description
`retry_policy`	object	required	Validation retry policy: activation, limit, interval, and eligible outcomes.
`enabled`	boolean	optional	`true` when the retry cycle is active. With `false`, the other fields are ignored. e.g. `true`
`max_retries`	integer (≥ 1)	optional	Maximum number of automatic retries. Once reached, the cycle enters the `exhausted` terminal state. The allowed limit depends on the plan. e.g. `3`
`interval_seconds`	integer (≥ 300, ≤ 86400)	optional	Seconds to wait between each retry (300–86400, i.e., 5 minutes to 24 hours). e.g. `600`
`outcomes`	array<string> (items: 1–?, unique items)	optional	Outcomes that trigger a retry. By default, they are `not_found`, `cep_unavailable`, and `error`; the combination `["not_found", "cep_unavailable"]` excludes `error`. e.g. `["not_found","cep_unavailable","error"]`

Request

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

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 with configuration, progress, and current status.
`enabled`	`boolean`	`true` when the validation has retries configured, even if its cycle has already ended (`terminal_state`). e.g. `true`
`max_retries`	`integer \| null`nullable	Configured maximum number of retries; `null` when `enabled` is `false`. e.g. `3`
`interval_seconds`	`integer \| null`nullable	Interval between retries in seconds, from `300` to `86400`; `null` when `enabled` is `false`. e.g. `600`
`outcomes`	`array \| null`nullable	Outcomes that trigger a retry: `not_found`, `cep_unavailable`, and `error`; `null` when `enabled` is `false`. e.g. `["not_found","cep_unavailable","error"]`
`attempts_completed`	`integer`	Number of retries completed so far. e.g. `1`
`next_attempt_at`	`TimestampUTC \| null`	Date of the next retry; `null` when none is scheduled.
`resolved_at`	`TimestampUTC \| null`	Date when a retry produced `valid`; `null` until that occurs.
`exhausted_at`	`TimestampUTC \| null`	Date when attempts were exhausted; `null` until that occurs.
`cancelled_at`	`TimestampUTC \| null`	Cycle cancellation date; `null` until that occurs.
`terminal_state`	`string \| null`nullable	Cycle state: `pending`, `resolved`, `exhausted`, or `cancelled`. It is `null` when the validation has no retry cycle. e.g. `pending`

**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.	`UpdateValidationRetryPolicyAttributes`
400	`4xx`	The request body is empty or is not valid JSON.	`ErrorResponse`
401	`4xx`	Authentication is required or the provided credentials are invalid.	`ErrorResponse`
403	`4xx`	Insufficient permissions.	`ErrorResponse`
404	`4xx`	Validation not found or not owned by the account (`not_found`).	`ErrorResponse`
410	`4xx`	The validation was purged and this resource no longer exists (`validation_purged`).	`ErrorResponse`
413	`4xx`	The request body exceeds the maximum accepted size (`body_too_large`).	`ErrorResponse`
422	`4xx`	Invalid policy or precondition not met. `retry_policy_invalid`, the shape, range, or outcome is not allowed; `retry_not_supported_for_bulk`, the validation came from an import; `retry_not_applicable`, its status is outside the three that admit a retry (`not_found`, `cep_unavailable`, `error`) or it changed meanwhile; `retry_already_resolved`, the cycle already closed; `retry_age_exceeded`, the validation is older than `max_age_seconds`; `retry_pending_cap_exceeded`, the account hit its pending cap or its 24-hour dispatched cap; `reactivation_cap_exceeded`, that validation hit its reactivation cap.	`ErrorResponse`

**Response headers**`200`
Header	Type	Description
`Idempotent-Replayed`	`string`	Only present when the request included `Idempotency-Key`. `true` marks a response reused from the idempotency cache, which remains valid for 24 hours per account, endpoint, and key.

**Errors from `PUT /v1/validations/{id}/retry-policy`**
Status	Code	Example
400	`body_empty`	The request body is empty. Envelope meta.request_id `c3d4e5f6a1b33b1a6f5e4d3c`
400	`invalid_json`	The body is not valid JSON. Envelope meta.request_id `d4e5f6a1b2c44c2b1a6f5e4d`
401	`unauthorized`	Invalid or missing authentication credentials. Envelope meta.request_id `c4d5e6f7a8b99b8a7f6e5d4c`
403	`permission_denied`	You do not have permission to access this resource. Envelope meta.request_id `d5e6f7a8b9c00c9b8a7f6e5d`
410	`validation_purged`	The validation was purged and this resource no longer exists. Envelope meta.request_id `1a2b3c4d5e6ff6e5d4c3b2a1`
413	`body_too_large`	The request body is too large. Envelope meta.request_id `1a2b3c4d5e6ff6e5d4c3b2a1`

Retry policy

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

Validation retry policy: activation, limit, interval, and eligible outcomes.

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

This operation accepts an optional retry policy.