Storyboard failures before implementing an API

For [API WORKFLOW] and [KNOWN CONTRACT], map the normal path and six failure states: bad input, authentication failure, timeout, duplicate request, partial downstream success and unavailable dependency. For each, specify HTTP response, idempotency key, logging fields, user-facing message and safe retry behaviour. Return a state table and minimal contract tests in the project's testing style. Distinguish documented API behaviour from design recommendations. Do not expose secrets in logs or invent an endpoint that the contract does not contain. End with the smallest experiment needed to validate the most uncertain failure path.