Audio job failed: read /events and /status before you retry

When a Sume TTS, STT or music job fails, it is terminal: read the status envelope and GET /v1/jobs/{id}/events for the reason, fix the input, and resubmit under a new Idempotency-Key. Resending the old key with the same body returns the same failed job, not a fresh attempt.

Failure causes and fixes

Codes below are the ones documented for audio routes; the fix column is what to change before the retry.

Fetch the reason

The submit envelope includes events_url, status_url and result_url. Terminal state is data.terminal on the status read.

import os, requests
H = {"Authorization": f"Bearer {os.environ['SUME_API_KEY']}"}
job = "job_123"
s = requests.get(f"https://api.sume.com/v1/jobs/{job}/status", headers=H).json()["data"]
print(s["terminal"], s["sume_status"])
if s["terminal"] and s["sume_status"] != "completed":
    ev = requests.get(f"https://api.sume.com/v1/jobs/{job}/events", headers=H)
    print(ev.json())

Gotchas

GET /result returns 409 job_not_completed until a job is done, so do not treat that as a failure. Whether a failed job is billed depends on how far it got; read usage on the job and the errors-and-credits page rather than assuming either way.