Spec safe retries for a bank without idempotency keys
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 /payoutstakes aclient_referenceof up to 35 characters and stores it with the payout, andGET /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?