Format run create: 202 fresh, 200 replay, 409 conflict in Python

How should your code read the response to a Format run create? 202 means Sume started a fresh run; 200 with idempotency_hit true means the same key and body already created one and you get its original receipt; 409 means the key was used with a different body, or another request with that key is in flight. Branch on status first, then code.

This is the retry story for an overnight series job. Network errors will happen across 40 episode submits, and the Idempotency-Key is what lets you resend safely.

The table

The scope of a key is one Format: the same key on two Formats starts two runs.

Classifier

The function below returns the next step as a string and works on the documented envelope, where errors live under error.code.

def classify(status: int, body: dict) -> str:
    if status == 202:
        return "started"
    if status == 200 and (body.get("idempotency_hit") or body.get("data", {}).get("idempotency_hit")):
        return "replay"
    code = body.get("error", {}).get("code", "")
    if status == 409 and code == "idempotency_key_in_use":
        return "retry_in_1s"
    if status == 409 and code == "idempotency_conflict":
        return "change_key_or_body"
    return "inspect"

print(classify(202, {}))
print(classify(200, {"idempotency_hit": True}))
print(classify(409, {"error": {"code": "idempotency_key_in_use"}}))

Choosing keys

Derive the key from the item: episode id plus a revision number you change when you want a new run. A time-based key defeats the mechanism. Edits to the instruction or the attachment list count as a different body, so a tweak with the old key is a 409, not a silent re-run.

Retries in practice

The idempotency key is what makes a retry safe. After a timeout, send the same key and the same body: you get 200 with idempotency_hit true and the original run, not a second charge. If you change the body but reuse the key, you get 409. Treat 409 as a bug in key reuse, not as a reason to retry blindly.

• Store the run id the first time you see it.
• Make keys deterministic per episode, such as the season and episode number.
• A 409 with key_in_use means the first request is still running; wait and ask again.

Wiring it into a worker

Call the classifier right after the HTTP response and branch on the result: new runs go to your tracking table, replays update nothing, and conflicts raise an alert. Keep the function pure so it is easy to unit test. A few fixture responses, one for each status code, are enough to cover it.