Entrega de eventos, idempotencia y manejo de duplicados

Enviar un evento a través de una red crea un resultado que el productor tal vez no pueda observar perfectamente. Puede ocurrir un tiempo de espera antes de que el servidor reciba una solicitud, mientras procesa la solicitud o después de aceptar el evento pero antes de que la respuesta llegue a la persona que llama. Volver a intentarlo mejora la entrega, pero también puede crear filas duplicadas.

Trate la política de entrega como parte del contrato del evento en lugar de una configuración SDK incidental.

Dar a cada evento lógico una identidad estable

Cree un event_id cuando se conozca el resultado de la aplicación. Reutilice ese identificador para cada intento de red que represente el mismo resultado. No genere un nuevo identificador dentro del ciclo de reintento.

const eventId = crypto.randomUUID();
const event = {
  event_id: eventId,
  job_id: job.id,
  status: "failed",
  error_type: "provider_timeout",
  attempt: job.attempt,
};

await sendWithBoundedRetry("job_completed", event);

Un event_id hace que los duplicados sean detectables; por sí solo no garantiza que el almacenamiento rechace todos los duplicados. Si el flujo de trabajo empresarial requiere efectos que se apliquen exactamente una vez, aplique ese requisito en el sistema propietario del efecto. Telemetry debe describir el resultado, no convertirse en el coordinador de transacciones de un pago, derecho o mutación de la base de datos.

Decidir qué errores se pueden volver a intentar

Vuelva a intentar fallas temporales de capacidad y transporte, como errores de conexión, 429, 502, 503 y 504. Respetar Retry-After cuando la respuesta lo proporcione. Utilice un retroceso exponencial con fluctuación y limite tanto el número de intentos como el tiempo total transcurrido.

No vuelva a intentar una solicitud 400 sin cambios. JSON, nombres de tablas, tipos de campos o esquemas no válidos requieren un cambio de productor. Reemplazar una credencial faltante o revocada después de 401; utilice una clave con el alcance requerido después de 403.

El referencia de límites de velocidad y errores API contiene las clases de respuesta y las reglas de reintento.

Mantenga la telemetría fuera de la ruta crítica de forma predeterminada

Para análisis operativos y de productos normales, una falla temporal de telemetría no debería convertir una solicitud exitosa de un cliente en un error. Limite el tiempo de espera de telemetría, informe una categoría de diagnóstico segura y continúe de acuerdo con la política de fallas del producto.

Algunos flujos de trabajo necesitan una entrega más sólida:

1. Registros de uso que alimentan la conciliación de facturación.
2. Eventos de auditoría de seguridad requeridos por un control aprobado.
3. Resultados comerciales irreversibles sin otra fuente de verdad.

En esos casos, escriba el resultado en una bandeja de salida duradera propiedad de la aplicación en la misma transacción que el cambio comercial. Un trabajador puede entregar el evento más tarde conservando su event_id original, la hora de aparición y la versión del esquema.

Medir entrega duplicada y faltante

Utilice ID de evento duplicados receta SQL para buscar identificadores con más de una fila almacenada. Divida los duplicados por productor, lanzamiento y motivo de reintento para que la solución se dirija a la ruta de entrega real.

Monitorear también:

• recuentos de eventos aceptados y rechazados por productor;
• edad del registro más antiguo de la bandeja de salida no entregado;
• intentos por evento lógico;
• fallas permanentes después del presupuesto de reintento;
• el retraso entre occurred_at y timestamp_utc.

Deduplicar cada consulta puede ocultar un productor roto. Mantenga visible el monitoreo de la tasa de duplicados incluso si un informe posterior selecciona una fila por event_id.

Pruebe los casos ambiguos

Ejerza un éxito, un rechazo definitivo, un fallo de conexión antes de la entrega y un tiempo de espera después de que el servidor haya aceptado el evento. Confirme que los reintentos reutilicen el ID del evento y que las respuestas de la aplicación sigan la política de error documentada.

Continúe con solución de problemas de ingesta de eventos, evolución del esquema y gestión de costes de telemetría.