Empezar · 02

Idempotencia

Las redes fallan: una petición puede llegar a Revísame y su respuesta perderse en el camino. La idempotencia te permite reintentar sin miedo a crear dos verificaciones o cobrar dos veces.

La regla

POST /v1/verificaciones exige el encabezado Idempotency-Key con el mismo valor que solicitud_id.

• Misma clave + mismo cuerpo: devuelve la misma verificación (por ejemplo, la misma que está en_proceso). No se crea otra ni se cobra de nuevo.
• Misma clave + cuerpo distinto: 409 conflicto_idempotencia. Nada se ejecuta.
• Sin la clave: 400 idempotency_key_ausente.

Cómo elegir solicitud_id

• Un identificador único por intento de verificación en tu sistema; recomendado: UUID v4.
• Opaco: no debe describir a la persona. Un solicitud_id o una webhook_url con palabras sobre salud, edad, estado civil, situación familiar, empleo o situación migratoria se rechaza con 400 peticion_invalida. Algunas palabras que el canal no emite provocan 400 vocabulario_no_permitido.
• Guárdalo antes de llamar a la API, para poder reintentar con el mismo valor después de una caída.

Cuándo usar uno nuevo

• Cuando la verificación anterior terminó en no_concluyente y quieres intentarlo otra vez (el reintento con la misma clave devolvería el mismo resultado).
• Cuando corriges datos (por ejemplo, una CURP rechazada con curp_invalida).

Reintentos recomendados

intento 1 → error de red / 500 / 503
espera 1 s  → mismo solicitud_id, mismo cuerpo
espera 2 s  → …
espera 4 s … hasta ~1 min, con variación aleatoria (jitter)

No reintentes errores 4xx distintos de 429: indican algo que hay que corregir.