Sume MCP idempotency_key: retry a timed-out paid call safely

Retry a paid call that timed out with the exact same idempotency_key and the exact same payload. Sume treats that as a retry, not a new job. A different key creates another job and bills again. The same key with a different payload fails with 409 idempotency_conflict.

Where the key is required

Writes and paid tools need idempotency_key under OAuth with write and under API keys. The docs describe it as a stable key for transport and dedup, not human approval. Reads do not need one.

Making keys retry-safe

Build the key from the work, not from the clock. A key made from a timestamp changes on retry and defeats the purpose.

• Derive it from stable inputs, for example scene-12-take-1.
• Store it with the job id as soon as the create returns.
• After a timeout, retry the create with the same key, or move to jobs_wait if you already have the job id.
• Change the key only when you mean to create new work.

Related limits

A 429 queue_full is retried with the same key once capacity frees up. A 503 provider_capacity_exceeded is retried later with the same key unless the error says not to. dry_run=true does not submit a job, so it needs no cleanup.

What the agent should record

Record three things per create: the key, the payload hash, and the job id once known. If the process dies after submit and before it saved the id, the key and payload let it retry safely. If it has the id, skip the retry and wait on the id instead.

A worked case

An agent submits generate_image with key hero-v1. The client times out. The agent retries with hero-v1 and the same payload: this is an exact retry. It then changes the prompt and reuses hero-v1: that is a different operation under the same key, and the server answers 409. The fix is to give the new prompt a new key, such as hero-v2.

Agents are good at forgetting what they did two turns ago, so write the rule where they will read it: before any paid call, look for an existing key and job id for this task; if one exists, wait on the id. If none exists, create the key, store it, and then submit. This three-step habit turns most timeout bugs into a harmless repeat of a read.

Keep in mind that Sume's hosted endpoint is the same for every client in this series: https://mcp.sume.com/mcp, with OAuth consent on the MCP host or an API key in a header. What differs is each client's config keys, its timeout defaults and its approval prompts. When a connection misbehaves, first separate those two layers: test the endpoint with curl and your credential, and only then look at the client's settings.