The diagnostic sequence

Ask these four questions in this order. Most integration failures are found by question two.

Order matters more than it sounds. Most people open the integration's own logs first, the middle of the pipeline, and lose an hour there before checking whether the source system ever sent the record. Each question rules out one place, so the next one is answerable instead of a guess.

Question 1

Is data leaving the source system correctly?

Before investigating the integration, confirm that the source system is producing the data it is supposed to produce. Check the most recent records that should have triggered the integration. Are they there? Do they have the expected field values? Was the trigger condition met?

A large share of "integration failures" are actually source system failures: a workflow step was disabled, a required field was left blank, the trigger condition changed when a process was updated. If the source data is correct and complete, move to the next question.

Question 2

Is the integration receiving the data at all?

Check the integration's log or error queue. Is it receiving events from the source system? Are the events arriving with the expected structure? If the integration has monitoring, what does it show for the period when the failure started?

If the integration is receiving data but producing no output, the problem is in the transformation or validation logic. If it is receiving no data, the problem is in the connection between the source system and the integration. These are different problems with different fixes.

Question 3

Is the data arriving in the expected format?

If the integration is receiving data but failing to process it, compare a sample of recent incoming data against the data contract or expected schema. Has a field been renamed? Has a previously optional field become required? Has a date format changed? Has an enumerated field added new values that the integration's mapping does not cover?

Format changes in the source system are the most common cause of integrations that were working correctly and then stopped. They rarely cause an immediate loud failure. They usually cause a silent failure where records are dropped or written with incorrect values.

Question 4

Is the destination system accepting the data?

If the integration is processing data correctly but the destination system is not showing the expected results, check the destination system's import log or API response codes. A field that was previously optional may now be required. A permission that allowed writes may have been changed. A rate limit may be causing some records to be dropped.

Destination system changes are less common than source system changes but can be harder to detect because the error often occurs silently in the integration layer rather than visibly in either system.

The answer that lies

A success code is a claim, not proof the write landed.

Question four checks the destination's response, but the response itself can be wrong. Plenty of systems return a 200 and then silently drop, truncate, or only partly apply the write. Diagnose against behaviour, not the contract.

Read back what you wrote. The only proof a write landed is finding it there afterwards. A 200 means the request was accepted, not that the record exists as sent, so for anything that matters, confirm by reading it back.

Watch for partial and silently-dropped writes. A batch can report success while discarding the rows it did not like, a rate limit can shed records without an error, and a field the destination does not recognise can be dropped without complaint.

Trust behaviour over the contract. The API docs say what should happen; production tells you what does. When the two disagree, believe the read-back and write the integration around the remote's real behaviour.

The monitoring question

The failure is almost always at the boundary, not inside either system.

With monitoring, diagnosis is reading a log to find where the failure started. Without it, you are reconstructing history from records in both systems, slower, and blind to anything that failed silently.

Common questions

Questions about diagnosing integration failures

At the boundary between the two systems. Check what the source system sent and what the destination system received. The failure is almost always in the gap between those two points, a transformation that produced unexpected output, a field that was renamed in the source, a filter condition that no longer matches. Looking at both ends before looking at the middle saves most of the time spent debugging integration failures.

You need logging that records what the integration did to each record. Without a log, a silent failure requires reconstructing the sequence of events from two disconnected systems, which is slow and often incomplete. If the integration does not have a log, adding volume monitoring is the fastest path to catching future silent failures: alert when the expected number of records processed drops to zero.

Something upstream changed, usually a field rename, a new required field, a changed enum value, or an API version update in the source system. Check the source system changelog if one exists, or compare the current API response structure against what the integration expects. Integration failures that appear suddenly after a period of stability are almost always caused by an upstream change that the integration was not designed to detect.