Spec safe retries for a bank without idempotency keys

Vibe codingHard25 minStripe style

Your task

Your Go service sends payouts through a bank's HTTP API. Calls sometimes time out, so the team wants a shared retry wrapper, WithRetry(ctx, op, policy), with exponential backoff and jitter. A coding agent will write it. The bank's API is old and has no idempotency keys, so sending the same payout twice pays twice.

Write the spec you would hand the agent.

What you know:

  • POST /payouts takes a client_reference of up to 35 characters and stores it with the payout, and GET /payouts?client_reference=... finds it
  • the bank sometimes takes 40 seconds to answer, and your HTTP client gives up after 15
  • during the bank's nightly maintenance window it returns 503, and then nothing was created
  • the wrapper will also serve read-only calls, such as balance checks

Then, in a few sentences: what does "retry the request a few times with backoff" get dangerously wrong here?