---
id: KB-IN-008
url: https://app.codecontract.io/help/integrations/what-to-do-when-the-integration-fails
idioma: en
categoria: integraciones
audiencia: desarrollador
nivel: avanzado
actualizado: 2026-08-13
tambienEn: [es]
relacionados: [KB-IN-005, KB-IN-007]
citadoPor: [KB-IN-016, KB-IN-018, KB-IN-019, KB-IN-020, KB-IN-009]
---

# When the integration stops working

_How to find out before the user does, and what to check first._

**Responde a:** the integration stopped working · webhooks are not arriving · api errors in production · monitoring an integration

A broken integration almost never announces itself. Everything looks fine until someone asks why a supplier is missing from the ERP, and by then it has been failing for two weeks.

## The four causes, by frequency

| Cause | How to spot it | Fix |
| --- | --- | --- |
| Key revoked or expired | Everything fails at once with an auth error | Rotate the key and update it |
| Your endpoint returns an error | Notifications retry and pile up | Check your logs, not ours |
| A field changed shape | Only one kind of operation fails | Compare what is sent against what is expected |
| Nobody watches the failures | Everything looks fine and half is missing | Alert on the failed queue |

> [!IMPORTANT]
> The fourth does the most damage and is the only one that raises no error: if nobody watches failed notifications, the integration looks healthy while losing half the events. Alert on that queue before anything else.

## The minimum to find out in time

**En corto**

- An alert if the failed queue rises above zero.
- A log on your side of what was received and what was done with it.
- A simple counter: events per day, alerting if it drops to zero.

> [!WARNING]
> Do not retry in an unbounded loop. An endpoint erroring on everything plus a sender retrying indefinitely produces days of noise and hides the real fault.

**Can lost events be resent?**

Retries have a window. Past it, reconcile by querying the API.

**How do I test without touching production?**

Against the test environment, with its own key.

**Should I alert on every failure?**

No: alert on the pattern, not the single event, or you will stop reading alerts.

## Ejemplos

**An ERP has received no notifications for two weeks and nobody noticed.**

- Finds its endpoint has been erroring since a deployment
- Adds an alert on the failed queue

→ The next failure is caught in hours instead of weeks.

**The integration has been down five days and it is discovered because a file is missing.**

- Sets an alert if activity stops arriving
- Reviews the call log weekly

→ The break is caught in hours rather than when somebody misses something.

**It fails and nobody knows whether the problem is on one side or the other.**

- Checks the call log with its error code

→ Diagnosis starts where it should look.

**It is retried by hand and files get duplicated.**

- Checks what arrived before reprocessing

→ The retry does not create what already existed.

**The key expired and nobody knew.**

- Records key expiries with a warning

→ Rotation happens before it cuts the service.

**It is fixed and no record remains of what happened.**

- Records the cause and what was done

→ Next time it is resolved in minutes.