Idempotency key for transcription: hash the request, avoid 409

Make the Idempotency-Key for a Sume transcription a hash of what the job means: the audio URL, the language code and the duration. A retry after a timeout sends the same key and gets the original job back with no second charge. Reusing a key with a different body is refused with 409 idempotency_conflict. Both rules are in Errors and rate limits and Jobs and results, read 2026-10-06.

Which keys fail, and why

A counter or a timestamp makes every retry a new job. A fixed string reused across clips makes the second clip a conflict. A hash of the request does neither: it is stable for the same intent and different for different intent. Keys can be up to 255 characters; a prefix plus 32 hex characters is plenty.

A key function

Serialize with sorted keys so the order of fields never changes the hash.

import hashlib, json


def stt_key(audio_url, language_code, duration_seconds):
    body = {"u": audio_url, "l": language_code, "d": duration_seconds}
    digest = hashlib.sha256(json.dumps(body, sort_keys=True).encode()).hexdigest()
    return f"stt-{digest[:32]}"


url = "https://media.sume.com/a.wav"
print(stt_key(url, None, 8))
print(stt_key(url, None, 8) == stt_key(url, None, 8))

What if I change the language on purpose?

A new language code is a new request, so the hash changes and the job is new and billed again. That is correct: you asked for a different transcription. If you meant to retry the first one, you changed the wrong thing.