Docs
EN

Objetivo

Configura una política de reintentos por defecto a nivel de cuenta para que cada nueva validación herede automáticamente un comportamiento de reintento consistente — sin necesidad de pasar retry_policy en cada body de POST /v1/validate o POST /v1/validate-ocr.

Requisitos previos

  • Una API key activa (mxcep_…). No se requiere permiso adicional — cualquier usuario autenticado puede leer y actualizar su propia política de reintentos.
  • Conocer los parámetros de reintento que deseas: outcomes elegibles, máximo de reintentos e intervalo.

Pasos

1. Leer la política actual

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

Si no se ha guardado ninguna política todavía, la respuesta devuelve un estado cero sintético:

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

Si ya hay una política configurada:

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

2. Actualizar la política

Envía el body completo de la política (no se admiten actualizaciones parciales):

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

Parámetros:

CampoTipoNotas
enabledbooleanRequerido. Establece false para deshabilitar los reintentos globalmente.
max_retriesintegerNúmero de intentos de reintento. Debe estar dentro del cap de tu plan.
interval_secondsintegerSegundos entre intentos. Debe estar dentro del rango permitido por el plan.
outcomesstring[]Qué veredictos disparan un reintento. Se requiere al menos un valor cuando enabled=true.

La validación es estricta — si max_retries o interval_seconds supera los caps de tu plan, el servidor devuelve 422 retry_policy_invalid. Revisa los detalles del error para los rangos permitidos.

Para deshabilitar los reintentos:

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. Usar Idempotency-Key para evitar escrituras duplicadas

Si tu despliegue reintenta peticiones PUT fallidas, usa Idempotency-Key para asegurarte de que la actualización de política se aplique solo una vez:

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

La respuesta incluye Idempotent-Replayed: true cuando la misma clave devuelve una respuesta cacheada (TTL 24h).

Siguientes pasos