Handle failures and retries

Map failure classes for POST /v1/batches: retryable vs fatal vs needs-human. Retries need budgets, jitter, and idempotency rules aligned to each input line has a stable custom_id; failed lines never poison the whole file. The chapter’s signature failure — duplicate custom_id causes silent overwrite of the better grade — must take a deliberate branch, not a generic catch-all.

Implement the degrade/rollback/refuse behavior QA lead who needs cost-capped offline eval by 07:00 UTC needs when BATCH-DUP-8841 repeats. Prefer scoped controls (one flag, one weight, one tenant, one secret version) over fleet-wide restarts. Preserve evidence; do not delete logs to “clean the demo.”

After containment, check batch_line_success_ratio ≥ 0.90 and dollars_per_1k_lines ≤ 8 moves in the safe direction and watch for retry amplification. Write the stop condition that ends the incident response for this lab.

Chaos note: inject only one fault class at a time and restore fixtures after. Watch for dual failures — dependency down and retry amplifier — which is how duplicate custom_id causes silent overwrite of the better grade becomes an outage. Customer communication templates (even if only for the drill) beat silence. If you queue deferred work, define poison-message handling. Budget documents should state the maximum extra spend allowed during retries. Close the loop by linking the containment action to a dashboard panel for batch_line_success_ratio ≥ 0.90 and dollars_per_1k_lines ≤ 8.

Draw a state diagram for degrade modes and put it in the repo as ASCII if needed. Cap concurrent retries across the process, not only per request. Ensure cancellation propagates to downstream HTTP clients. When failing closed, choose a user-visible message that does not leak internals. Practice the single command that flips the kill switch or weight to zero. After recovery, drain or inspect deferred work before declaring green. In this chapter the product is overnight batch job that grades 50k support transcripts via provider Batch API, the human stakeholder is QA lead who needs cost-capped offline eval by 07:00 UTC, and the incident id you design against is BATCH-DUP-8841. Re-state the oracle in your notes — fixture of 20 lines yields 18 succeeded + 2 failed with error objects; cost ≤ $0.40 — and keep the invariant visible: each input line has a stable custom_id; failed lines never poison the whole file. Track batch_line_success_ratio ≥ 0.90 and dollars_per_1k_lines ≤ 8 as the scoreboard. Surface under change control: POST /v1/batches. If you only have forty minutes, finish the fixture for duplicate custom_id causes silent overwrite of the better grade before polishing UI. Promotion language stays ternary: promote, hold, or roll back based on evidence, not hope.