Make the unhappy path clear.

Transport, format, and analysis are separate layers.

A successful network request can still return a malformed document. Valid JSON can still fail a schema. A structurally valid report can still describe an incomplete collection. Handle each layer explicitly so the interface does not turn a failure into an empty but successful-looking chart.

Condition	Consumer behavior
Network or HTTP failure	Preserve the status and request context. Offer a retry only when the operation is safe to repeat.
Invalid JSON	Stop parsing, show a readable error, and avoid rendering invented defaults.
Schema mismatch	Identify the invalid field without exposing sensitive payloads in logs.
Partial report	Render completed findings alongside the missing scope.
Failed report	Show the report summary and explain that no completed findings are available.

Test a partial result.

The partial fixture contains one completed observation and explains which parts of the document were not provided. A consumer should not infer that the uninspected parts passed their checks.

Download partial fixture

Test a failed result.

The failed fixture contains no findings. Its summary explains that parseable input was unavailable. Treat this as an unsuccessful analysis, not as evidence that the target had no issues.

Download failed fixture

Keep retries bounded.

In your own live integration, decide which operations can be safely repeated, use a stopping condition, and follow the provider’s documented retry behavior. Do not retry invalid input without changing it. Preserve useful completed results when the workflow can resume only the unfinished work.

Design the recovery message too.

Tell the user what happened and what they can do next. “The report could not be parsed” is different from “the source could not be reached.” Neither state should silently produce zero values. The reliable integration guide connects these ideas to a complete request workflow.