Retry an image edit after a timeout: same key, same payload

When an image edit times out on your side, send the identical request with the identical Idempotency-Key; when you change anything that matters (prompt, reference, quality), use a new key. Sume's docs state the rule directly: use the same key again only for the same operation and payload. The retry then returns the original job instead of billing a second one.

Why a timeout is not a failure

A client timeout tells you your process stopped waiting, not that Sume stopped working. The Jobs and results docs say not to submit the original paid request again only because a local process timed out. Poll GET /v1/jobs/{id}/status if you have the id. If you do not, retry the submit with the same key.

What to do with the 202 case

A 202 is not an error. It means Sume accepted the work and it did not finish inside the wait. The docs say the image route blocks for up to 30 seconds, then returns 202 with the job envelope. In that case you must not submit again; poll status_url until terminal is true, and obey next_poll_after_seconds when it is present. Then fetch the result from result_url.

A client timeout is a different case. You may not have seen the 202 at all, because your client gave up first. That is when the same-key retry saves you.

Mistakes to avoid

• Generating a random key on every attempt. It defeats the purpose and can double bill.
• Reusing one key for a whole batch. Each edit needs its own key.
• Retrying a 402 insufficient_credits in a loop. Add funds first.
• Retrying a 400 without changing the request. The request is wrong, not unlucky.

Which key for which case

A key scheme

Make keys readable and deterministic, so a crashed script resumes safely. Build them from your own ids: edit-{asset_id}-{prompt_version}-{quality}. The same asset with the same prompt version and quality always yields the same key. Bump prompt_version when you change the prompt. That makes the rule automatic and keeps an audit trail.

One caution: a key does not make a completed bad image free: a completed edit is billed in full, as the Image API docs say. A failed or cancelled one is not.

A last point on keys. Make them easy to trace: build each from the business object and the operation, for example the asset id plus the edit name plus a version. When something looks wrong in your logs you can then tell at a glance which operation a request belonged to, and whether a retry used the same key as its first attempt. Never put secrets or personal data in a key. Keep the scope of this advice in view. It rests on the Sume docs and the vendor pages named in the sources, read on 2026-10-05, and on nothing measured by Sume. Where a behavior depends on your own images, such as how a model redraws a certain typeface, run a small pilot at the low quality tier and judge the result yourself before you plan a batch. Write down the prompt, the model id and the quality tier you used, so the run can be repeated. When the catalog or the docs change, re-read them; the live catalog is the contract, and a post is only a snapshot of it.