---
id: KB-IN-008
url: https://app.codecontract.io/ayuda/integraciones/que-hacer-cuando-la-integracion-falla
idioma: es
categoria: integraciones
audiencia: desarrollador
nivel: avanzado
actualizado: 2026-08-13
tambienEn: [en]
relacionados: [KB-IN-005, KB-IN-007]
citadoPor: [KB-IN-016, KB-IN-018, KB-IN-019, KB-IN-020, KB-IN-009]
---

# Cuando la integración deja de funcionar

_Cómo enterarse antes que el usuario, y qué mirar primero._

**Responde a:** la integración ha dejado de funcionar · los webhooks no llegan · errores de la api en producción · monitorizar una integración

Una integración rota casi nunca avisa. Sigue todo verde hasta que alguien pregunta por qué un proveedor no aparece en el ERP, y para entonces lleva dos semanas fallando.

## Las cuatro causas, por frecuencia

**Por qué una integración rota no avisa** — El aviso sale y se reintenta; el error ocurre en vuestro endpoint, así que desde la plataforma todo sigue en verde. Lo único que lo destapa es una alerta sobre la cola de fallidos.

| Causa | Cómo se reconoce | Arreglo |
| --- | --- | --- |
| Clave revocada o caducada | Todo falla de golpe, con error de autenticación | Rotar la clave y actualizarla |
| Vuestro endpoint devuelve error | Los avisos se reintentan y se acumulan | Mirar vuestros logs, no los nuestros |
| Un campo cambió de forma | Falla solo un tipo de operación | Revisar qué se envía frente a lo que se espera |
| Nadie mira los fallidos | Todo parece bien y falta la mitad | Poner una alerta sobre la cola de fallidos |

> [!IMPORTANT]
> La cuarta es la que más daño hace y la única que no da error: si nadie mira los avisos fallidos, la integración parece funcionar mientras pierde la mitad de los eventos. Poned una alerta sobre esa cola antes que sobre nada más.

## Lo mínimo para enterarse a tiempo

**En corto**

- Una alerta si la cola de fallidos pasa de cero.
- Un registro en vuestro lado de qué se recibió y qué se hizo con ello.
- Un contador simple: cuántos eventos por día, y avisar si baja a cero.

> [!WARNING]
> No reintentéis en bucle sin límite. Un endpoint que responde error a todo y un emisor que reintenta indefinidamente generan ruido durante días y esconden el fallo real.

**¿Se pueden reenviar los eventos perdidos?**

Los reintentos tienen un plazo. Pasado, hay que reconciliar consultando por la API.

**¿Cómo pruebo sin tocar producción?**

Contra el entorno de pruebas, con su propia clave.

**¿Conviene alertar de cada fallo?**

No: alertad del patrón, no del evento suelto, o dejaréis de mirar las alertas.

## Ejemplos

**Un ERP lleva dos semanas sin recibir avisos y nadie se ha dado cuenta.**

- Descubre que su endpoint devolvía error desde un despliegue
- Añade una alerta sobre la cola de fallidos

→ El siguiente fallo se detecta en horas en vez de en semanas.

**La integración lleva cinco días caída y se descubre porque falta un expediente.**

- Configura un aviso si deja de llegar actividad
- Revisa el registro de llamadas cada semana

→ El corte se detecta en horas y no cuando alguien echa algo en falta.

**Falla y nadie sabe si el problema es de un lado o del otro.**

- Consulta el registro de llamadas con su código de error

→ El diagnóstico empieza donde hay que mirar.

**Se reintenta a mano y se duplican expedientes.**

- Comprueba qué llegó antes de reprocesar

→ El reintento no crea lo que ya existía.

**La clave caducó y nadie lo sabía.**

- Registra el vencimiento de las claves con aviso

→ La rotación se hace antes de que corte el servicio.

**Se arregla y no queda constancia de qué pasó.**

- Registra la causa y lo actuado

→ La siguiente vez se resuelve en minutos.