Format run failed provider_unavailable or mcp_unavailable: retry rules

provider_unavailable and mcp_unavailable are failures on Sume's side of a Format run, not your input, and both are retried with a new Idempotency-Key. provider_credits_exhausted is also Sume's side, but it is not retried right away. All three are in the run-time failure table of the Errors and spend docs.

Treat the set as open: new codes may appear, so handle the ones you know and fall through on the rest.

What does each code mean?

These codes arrive on a run that already exists, as status: "failed" with error: { code, message }, in the run-time failure table of the Errors and spend docs.

Why a new Idempotency-Key?

The old key is bound to the receipt you already have. Replaying it with the same body returns that receipt with idempotency_hit: true and starts nothing, which is exactly what you want after a network blip and exactly what you do not want after a failed run. Derive the key from the thing being made plus an attempt counter, such as order-8823-v1-retry-1.

If the failed run left clips behind, prefer continuing it with previous_run_id over a fresh run, as the docs advise.

How do I encode this in a webhook handler?

Over a webhook the same run arrives with status: "ERROR", outcome: "error" and error.code mirroring the receipt. Dedupe on request_id, which repeats on every retry. Here is a small decision function you can run with Node 18 or later:

const RETRY_NEW_KEY = new Set(["mcp_unavailable", "provider_unavailable"]);
const WAIT = new Set(["provider_credits_exhausted"]);

function decide(run, attempt) {
  const code = run.error?.code;
  if (!code) return { action: "none" };
  if (RETRY_NEW_KEY.has(code)) {
    return { action: "retry", key: `order-8823-v1-retry-${attempt + 1}` };
  }
  if (WAIT.has(code)) return { action: "retry_later" };
  return { action: "inspect", code };
}

console.log(decide({ error: { code: "provider_unavailable" } }, 0));
console.log(decide({ error: { code: "provider_credits_exhausted" } }, 0));
console.log(decide({ error: { code: "unattended_blocked" } }, 0));

What is billed on a failure?

Generation that finished before a failure or cancel is billed, and a later step failing does not refund it. For mcp_unavailable the docs state details.charged is false: no generation ran. Read usage.billable_amount_usd_micros against usage.generation_spend_cap_usd_micros on the receipt, since a run that wanted to spend past its cap lands on the generic format_run_failed.

A create-time 4xx, an idempotent 200 replay and a skipped run cost nothing. See Sume Format run failure codes for the codes that do need a change on your side, such as unattended_blocked.

How many times should I retry?

The docs give no attempt limit, so choose one and cap your own spend. Retry once with a new key, then contact support with the request_id if the same code repeats, which is the documented advice for the generic format_run_failed_to_start as well. If mcp_unavailable repeats, the docs' reading is that the tools are down, not your request.