Set default retry policy

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

Audience: public
Auth: API key
Permission: users:update_self

Configures the default retry policy for the authenticated user. Once saved, it is applied to all future validations that do not specify their own retry_policy in the body. Validation is strict (no silent clamping — exceed the caps and the request is rejected). Accepts optional Idempotency-Key to prevent duplicate writes on network retries.

Parameters
Parameter	In	Type	Required	Description
`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	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/users/me/retry-policy' \
  -H 'Authorization: Bearer veriko_••••' \
  -H 'Content-Type: application/json' \
  -d '{
    "retry_policy": {
      "enabled": false
    }
  }'

Python example — coming soon.

JavaScript example — coming soon.

PHP example — coming soon.

**Response 200**`RetryPolicy` — Retry policy updated (echo of the normalized body).
Field	Type	Description
`enabled`	`boolean`	Enables or disables the retry cycle for this validation. If `false`, the other fields are ignored. e.g. `true`
`max_retries`	`integer`	Maximum number of automatic retries. Once reached, the cycle enters the `exhausted` terminal state. The upper bound depends on the plan (`retry_max_retries`) or the global default `max_retries_cap` (typically 5–10). e.g. `3`
`interval_seconds`	`integer`	Seconds to wait between each retry (300–86400, i.e., 5 minutes to 24 hours). e.g. `600`
`outcomes`	`array` (items: 1–?, unique items)	Validation outcomes that trigger a retry. By default the cycle activates on `not_found`, `cep_unavailable` and `error`; clients that do not want to retry Banxico HTTP 5xx errors can send `["not_found", "cep_unavailable"]`. e.g. `["not_found","cep_unavailable","error"]`

**Response status codes**`PUT /v1/users/me/retry-policy`
Status	Class	Description	Body
200	`2xx`	Retry policy updated (echo of the normalized body).	No body
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`
413	`4xx`	The request body exceeds the maximum accepted size (`body_too_large`).	`ErrorResponse`
422	`4xx`	Retry policy is invalid (`retry_policy_invalid`). Causes: `enabled` missing or not boolean; `max_retries` outside `[1, max_retries_cap]`; `interval_seconds` outside `[min_interval_seconds, max_interval_seconds]`; `outcomes` empty when `enabled=true`; outcome outside the allowlist (`eligible_outcomes` from config/validation_retries.php).	`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/users/me/retry-policy`**
Status	Code	Example
400	`body_empty`	The request body is empty. Envelope meta.request_id `b0c1d2e3f4a5`
400	`invalid_json`	The body is not valid JSON. Envelope meta.request_id `c1d2e3f4a5b6`
401	`unauthorized`	Invalid or missing authentication credentials. Envelope meta.request_id `c4d5e6f7a8b9`
413	`body_too_large`	The request body is too large. Envelope meta.request_id `1a2b3c4d5e6f`

Retry policy

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