examples/api-500.md

# Example: API 500 with Optional Datadog Evidence

## Input

Customer reports:
- POST /invoice → HTTP 500
- request_id: req_82a91
- timestamp: 2026-09-03 14:32:17 UTC
- production

Available evidence:
- Datadog trace for req_82a91 shows NullPointerException in InvoiceService at 14:32:17 UTC.
- Release 2026.09.03.1 began serving at 14:31:58 UTC.
- Jira BUG-1842 contains the same exception fingerprint and identifies a null tax-profile edge case introduced in the release.
- Two other failures on the same release share the fingerprint.

## Good assessment

Observed:
- Customer request failed with HTTP 500.
- Same request ID maps to the InvoiceService exception.
- The release preceded the failure by 19 seconds.
- BUG-1842 matches the exception fingerprint.
- Similar failures exist on the same version.

Inferred:
- The release is strongly associated with the failure.
- BUG-1842 is likely the relevant defect.

Root Cause Assessment:
- Highly Likely
- Confidence: High
- Likely application regression in invoice creation for the null tax-profile state.

Falsification:
- Check whether the same fingerprint occurs on pre-release/old-version traffic. If it does, reduce deployment-causation confidence.

Customer-safe response:
"The evidence points to an application issue affecting invoice creation for this request. We are checking whether the matching known defect explains this failure and will share the next confirmed step."

Do not expose stack traces, private Jira links, or internal release infrastructure.