Failure handling and expected output in an integration example

Choose the failure that teaches the boundary

Select a failure that occurs at an important boundary in the documented workflow. Expired authentication teaches credential ownership. A permission denial teaches role requirements. Invalid input teaches schema validation. A rate limit teaches backoff or queue behavior. An incompatible version teaches support policy. Do not choose a contrived typo merely because it is easy to reproduce.

Describe the starting state, command or request, expected error status, stable part of the message, and absence of an unintended side effect. If a request creates a resource before failing later, show how to find and remove the partial state. A failure example should not ask readers to paste production tokens into a shell history or intentionally damage a live account.

Separate retryable from held conditions

State whether the client may retry, must refresh authentication, must change the request, or should stop and contact the product owner. Automatic retries need a limit, delay policy, and idempotency assumption. A recipe should not prescribe retry for every server error because repeated state-changing requests can duplicate work when the outcome of the first request is unknown.

Google's command-line documentation advises presenting commands that can run without editing where possible. Use that discipline for recovery commands too. If a value must change, name it before the block and validate it. Capture the expected recovery output and final state so a reader can tell whether the system recovered or merely stopped printing an error.

Record what remains untested

A single failure path does not represent the product's whole error model. List relevant exclusions such as regional behavior, high-volume limits, concurrent writes, revoked organization access, or provider outages. Link to authoritative product documentation for broader error semantics. The recipe's acceptance check should cover only the path and environment named in its receipt.

Integration Atlas tests and records the selected failure through Reality Contact, LLC. The buyer decides which errors belong in public product guidance, supplies safe test conditions, and owns incident and support policy. The service does not promise that all errors are recoverable or that an example remains accurate after an unreviewed product or dependency change.

Where the service stops

Reality Contact, LLC writes, tests, and packages integration documentation but does not certify the underlying product, guarantee compatibility with untested environments, operate production accounts, provide ongoing support outside the written period, or decide which product behavior the buyer promises. The buyer supplies safe access and the authoritative product contract, chooses the supported environments, resolves product ambiguities, approves each public recipe, and assigns an owner for future release-triggered maintenance. This developer-documentation and example-testing work does not replace the buyer's engineering, security, legal, compliance, or production-operations review, and it is not a promise that every customer environment will behave the same way. The buyer approves public product statements, supported combinations, credentials policy, and release status before any recipe is published.