Ir al contenido

Reintentos e idempotencia

Al terminar esta página sabrás cuántas veces y con qué espaciado Neat reintenta un webhook no confirmado, y cómo usar Idempotency-Key para que reintentar una request desde tu servidor nunca abra un cobro duplicado.

Neat espera hasta 9 segundos por una respuesta a cada entrega. Confirma la entrega con cualquier 2xx. Se reintenta con espera creciente cuando no respondes, cuando la conexión falla y cuando respondes 408, 429 o cualquier 5xx. Cualquier otra respuesta se toma como un rechazo definitivo: la entrega queda marcada como fallida y no se reintenta, porque un 400 o un 404 no mejoran solos. Si tu endpoint devuelve 4xx por una caída temporal, devuelve 503 en su lugar.

La espera crece así:

Intento Espera hasta el siguiente
1 2 minutos
2 4 minutos
3 8 minutos
4 16 minutos
5 32 minutos
6 64 minutos
7 128 minutos
8 en adelante 256 minutos

Neat reintenta hasta 12 veces o durante 24 horas desde el primer intento, lo que ocurra primero. Al agotarse, el evento queda marcado como no entregado y Neat no lo reintenta más por su cuenta; el cobro sigue visible en GET /v1/checkout-sessions/{sessionId}. Estos tiempos describen el comportamiento actual de la API, no un compromiso contractual.

El timestamp y la firma se renuevan en cada intento; event_id y el cuerpo permanecen iguales entre reintentos del mismo evento.

Guarda el evento por su event_id y responde 2xx de inmediato; procesa el efecto (marcar la obligación como pagada, por ejemplo) de forma asíncrona si tu procesamiento puede tardar. Una respuesta lenta cuenta como no confirmada a los 9 segundos y dispara un reintento, aunque tu servidor sí lo haya recibido.

La entrega es al menos una vez: el mismo evento puede llegar más de una vez, incluida una entrega después de que ya lo procesaste. Guarda los event_id que ya procesaste y responde 2xx sin volver a aplicar el efecto ante uno repetido.

Idempotency-Key es obligatoria en POST /v1/checkout-sessions. Sin ella, la API responde 422 VALIDATION_ERROR con "field": "Idempotency-Key". Usa entre 8 y 128 caracteres ASCII ([A-Za-z0-9._:-]).

La llave identifica esa solicitud de creación, no un cobro. Si tu llamada termina en timeout o no recibes respuesta, repite exactamente la misma llave con exactamente el mismo cuerpo.

Situación Resultado
Llave nueva Crea una sesión nueva (sujeto a las reglas de external_reference, ver Sesiones de checkout).
Misma llave, mismo cuerpo Devuelve la misma respuesta guardada, mismo session_id, mismo checkout_url, mismo expires_at, con 201 Created otra vez, aunque esa sesión ya haya vencido. No abre una segunda sesión.
Misma llave, cuerpo distinto 409 IDEMPOTENCY_CONFLICT.
Sin cabecera Idempotency-Key, o con un formato inválido 422 VALIDATION_ERROR, "field": "Idempotency-Key".

La comparación de “mismo cuerpo” es sobre el contenido ya validado del request, no sobre el texto literal: cambiar el orden de las propiedades del JSON no cambia el resultado.

Los registros de Idempotency-Key no expiran: la misma llave con un cuerpo distinto responde 409 IDEMPOTENCY_CONFLICT indefinidamente. Genera una llave nueva por cada intento de cobro, por ejemplo un UUID, y guárdala junto a ese intento: el reintento de esa llamada usa la misma llave, y un intento nuevo, otra. Una llave fija en tu código, o copiada de un ejemplo, sólo sirve para la primera sesión.

La API no expone hoy un código de error para dos solicitudes simultáneas con la misma llave mientras la primera se procesa. No envíes la misma llave en paralelo; reintenta solo después de un timeout o de una respuesta perdida.