Retry a Format 402 with the same Idempotency-Key after adding funds

Yes, reuse the same Idempotency-Key. The Format call guide says that after a create that failed with 402, Sume released the key, so you correct the cause and retry with the same key. Nothing ran on the 402, so there is no charge to reverse.

What each outcome costs

The Format errors page lists two money gates. The wallet is checked at create, and the spend cap applies during the run. A 402 belongs to the first gate.

The retry sequence

Follow the order below. Do not generate a new key unless you want a second run.

• Read next_action; for insufficient_credits it is add_funds.
• Top up in the dashboard. The public Developer API gives balance and usage reads, but no top-up endpoint.
• Resend the same request body with the same Idempotency-Key.
• If the key is reused with a different body or operation, expect 409 idempotency_conflict and no run.

Handling it in code

The SDK runs page shows a catch for SumeRunRequestError that checks status === 402 or code === "insufficient_credits", then alerts with the request id. Keep the idempotency key beside the job in your own queue, so the retry after a top-up reuses it. A key belongs to one Format, so sending it to a second Format starts a second run.

A worked example

A nightly job creates 30 runs with keys order-1001-v1 to order-1030-v1. At run 19 the wallet is empty and create returns 402. Runs 1 to 18 are accepted and keep their receipts. After a top-up, the job resends the same key for run 19 and continues to 30. If the job were to restart from run 1 with the same keys, runs 1 to 18 return 200 with idempotency_hit: true and no second charge.

This is why the docs advise deriving the key from the item and a version, not from the time. Bump the version, for example to -v2, only when you want a real re-run of that item.

• Keys are up to 255 characters.
• A key's scope is one Format.
• A random uuid per request disables the protection.