Docs
ES

Goal

Configure a default retry policy at the account level so that every new validation automatically inherits a consistent retry behavior — without you needing to pass retry_policy in every POST /v1/validate or POST /v1/validate-ocr request body.

Prerequisites

  • An active API key (mxcep_…). No additional permission is required — any authenticated user can read and update their own retry policy.
  • Know the retry parameters you want: eligible outcomes, max retry count, and interval.

Steps

1. Read the current policy

curl 'https://api.example.com/v1/users/me/retry-policy' \
  -H 'Authorization: Bearer mxcep_••••'

If no policy has been saved yet, the response returns a synthetic zero-state:

{
  "data": {
    "type": "retry_policy",
    "attributes": {
      "enabled": false,
      "max_retries": 0,
      "interval_seconds": 0,
      "outcomes": []
    }
  }
}

If a policy is already configured:

{
  "data": {
    "type": "retry_policy",
    "attributes": {
      "enabled": true,
      "max_retries": 3,
      "interval_seconds": 600,
      "outcomes": ["not_found", "cep_unavailable"]
    }
  }
}

2. Update the policy

Send the full policy body (no partial updates):

curl -X PUT 'https://api.example.com/v1/users/me/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"]
    }
  }'

Parameters:

FieldTypeNotes
enabledbooleanRequired. Set false to disable retries globally.
max_retriesintegerNumber of retry attempts. Must be within your plan's cap.
interval_secondsintegerSeconds between attempts. Must be within the plan-allowed range.
outcomesstring[]Which verdicts trigger a retry. At least one value required when enabled=true.

Validation is strict — if max_retries or interval_seconds exceeds your plan's caps, the server returns 422 retry_policy_invalid. Check the error details for the allowed ranges.

To disable retries:

curl -X PUT 'https://api.example.com/v1/users/me/retry-policy' \
  -H 'Authorization: Bearer mxcep_••••' \
  -H 'Content-Type: application/json' \
  -d '{
    "retry_policy": { "enabled": false }
  }'

3. Use Idempotency-Key to prevent duplicate writes

If your deployment retries failed PUT requests, use Idempotency-Key to ensure the policy update is applied only once:

curl -X PUT 'https://api.example.com/v1/users/me/retry-policy' \
  -H 'Authorization: Bearer mxcep_••••' \
  -H 'Idempotency-Key: policy-update-2025-03-15-v1' \
  -H 'Content-Type: application/json' \
  -d '{ "retry_policy": { "enabled": true, "max_retries": 3, "interval_seconds": 600, "outcomes": ["not_found"] } }'

The response includes Idempotent-Replayed: true when the same key returns a cached response (TTL 24h).

What's next