Start with the symptom you can observe.
Use the row that matches the available evidence. A symptom narrows the next check; it does not diagnose the cause.
| Observed symptom | Inspect next | Do not conclude yet |
|---|---|---|
| Expected work never starts | Source transition history, trigger configuration and eligibility at that time. | The current source state does not prove the trigger fired. |
| An event was emitted; receipt is unconfirmed | Delivery attempts and receiving logs for the same event ID and time window. Check log coverage. | A missing log line does not establish non-delivery. |
| The destination rejects a request | Per-record response, submitted fields, validation rules and permission scope. | Do not repair a guessed cause or assume every rejected request is safe to replay. |
| A documented rate-limit response, such as 429 | Applicable provider limit, retry guidance and whether an existing job or worker retains D-482. | A rejected attempt does not by itself establish permanent loss or permission to create a duplicate job. |
| Processing is accepted; completion is pending | The returned job ID and documented completion status or destination record. | Acceptance is not completion; respect the documented processing interval. |
| The run succeeds; the task is missing or wrong | Mapping output and authoritative destination state for the same operation. | A green run does not establish the intended owner, values or number of tasks. |
The diagnostic sequence
Trace one record through these four checks.
Keep deal D-482, event EVT-482-1 and run RUN-731 beside the investigation. The identifiers below are fictional. Compare timestamps in one stated time zone and retain the original evidence before making corrections.
Question 1
Is data leaving the source system correctly?
Inspect the historical transition and the trigger rule that applied then. Confirm which field changed, when it changed and whether that intake path emits the required event. A record that looks correct now may have been incomplete when the workflow evaluated it.
For D-482, the source history records a Won transition at 09:00:00 UTC on 12 October 2026. The emission record identifies EVT-482-1. This establishes a source event to trace; it does not establish receipt.
Question 2
Is the integration receiving the data at all?
Find a receipt for EVT-482-1 and the receiving run. Check whether logs cover the relevant time window, are sampled or have expired. If no receipt is found, retain delivery attempts and mark receipt unconfirmed until those limits are understood.
RUN-731 records receipt at 09:00:02 UTC. The event reached the integration. Its later failure must be investigated without assuming the source was healthy in every other respect.
Question 3
Is the data arriving in the expected format?
Compare the received payload and transformed output with the agreed schema and mapping version. Check required fields, types, enumerated values and the authoritative source for each mapped field.
The received D-482 event has account_owner_id O-17. Mapping v3 writes task.assignee_id from a missing deal_owner_id instead, producing a blank assignee. The missing output is observed; the mapping is the suspected cause until checked against the contract.
Question 4
Is the destination system accepting the data?
Read the response for the same request, including per-record errors. Then inspect any job result and authoritative destination state. Rejections, queued requests and completed writes require different recovery actions.
At 09:00:03 UTC, request REQ-731 returns 422 with assignee_id required. In this fictional endpoint contract, validation rejection creates no task. The request audit and lookup by operation ONBOARD-D-482 confirm no task was created. A different endpoint needs its own evidence.
For a rate-limited attempt, inspect the provider’s documented retry contract and existing queue before scheduling more work. A 429 does not tell you whether your integration retains the record. Keep the next permitted attempt and business deadline visible; provider-specific Retry-After units and retry behavior must be checked rather than assumed.
Follow D-482 from rejection to one verified task.
All records, timestamps, identifiers and response behaviour in this example are fictional. The scenario illustrates the method; it is not a client result or a universal endpoint contract.
| Time (UTC) | Evidence retained | What it establishes |
|---|---|---|
| 12 Oct 2026 · 09:00:00 | D-482 changes to Won; source emits EVT-482-1. | The expected trigger event exists. |
| 09:00:02 | RUN-731 receives EVT-482-1 with account_owner_id O-17. | Receipt is confirmed for this event. |
| 09:00:03 | Mapping v3 produces blank task.assignee_id; REQ-731 returns 422, assignee_id required. | The request was rejected. The endpoint contract and destination audit confirm no task was created. |
| 09:12:00 | The CRM owner confirms O-17 is active and authorised. The integration owner approves mapping v4: account_owner_id to task.assignee_id. | The repair has an accountable decision and an approved field mapping. |
| 09:15:00 | A supervised recovery RUN-732 submits REQ-732 for operation ONBOARD-D-482 with assignee O-17. The documented idempotency key covers task creation and remains valid. | The recovery follows this endpoint's contract; the key is not a substitute for checking the previous outcome. |
| 09:15:02 | REQ-732 returns 201 and task T-906. The authoritative task lookup and operation audit show one task for D-482, assigned to O-17. | The intended business result is verified. Link both runs and close the incident with the owner. |
Response evidence
Check what the response confirms.
HTTP 200 means the request succeeded; HTTP 202 means it was accepted but processing has not completed. The endpoint contract explains what that success covers. A successful submission can still leave a later business step pending, and a batch response may contain individual failures.
Inspect the documented result: response fields, per-record outcomes and any job or completion identifier. Match them to the original operation.
Verify a consequential result through an authoritative record or completion status. Account for documented visibility delays; a blank immediate lookup does not prove that nothing happened.
When observed behaviour disagrees with the contract, retain both pieces of evidence and hold unsafe recovery. Do not replay an uncertain write just to see whether it works this time.
The monitoring question
Find the last confirmed step before deciding what to repair.
Logs help only when their coverage is known. Sampling, retention gaps, missing correlation IDs and unlogged downstream actions limit what an investigation can establish. Keep those gaps visible. Record-level tracing and expected-activity monitoring answer different questions; choose monitoring that fits the workflow.
Before retrying
Recover only after the previous outcome is understood.
01
Establish the previous outcome
Match the request to destination records, job status and audit evidence. If a write may have succeeded, investigate before replaying it.
02
Check the recovery contract
Read the endpoint retry rules, deduplication scope, key retention and ordering constraints. A transient error and a validation rejection need different responses.
03
Confirm the repair
Have the responsible owner approve the corrected field, permission or mapping. Retain the failed input and approved change.
04
Run supervised recovery
Recover the identified operation through the authorised mechanism. Keep the original and recovery identifiers linked; do not blindly replay every event.
05
Reconcile the business result
Verify the intended record, owner and task count in the authoritative destination. Record residual uncertainty and close only when the acceptance condition is met.
Common questions
Questions about diagnosing integration failures
Choose one expected record and trace its source state, emitted event, receipt, processing and destination result. Comparing both ends helps locate the gap, but a source, queue, permission or destination fault may be responsible. Use evidence to choose the next check.
Trace one expected record using source history, delivery attempts, receiving logs and authoritative destination state. Check log coverage and retain gaps as unknowns. Expected-activity monitoring can reveal missing work, but does not explain which record or step failed on its own.
Compare a recent successful operation with a failed one and inspect changes to both systems, permissions, schedules, volume and dependencies. A renamed field or API version is one possibility, not a diagnosis. Confirm which step changed before choosing a repair.
First establish whether the previous operation took effect. Check the endpoint contract and the scope and retention of any idempotency key. Correct the confirmed fault, then use an authorised supervised recovery and reconcile the destination. A timeout or missing acknowledgement does not prove the write failed.
