Moltline Studio Get a license

Blog

Retries and Idempotency for Failed Paid Tool Calls

Professional header image for step-by-step guide: Retries and Idempotency When a Paid Tool Call Fails Mid-Run

A paid tool call that fails mid-run leaves a licence bought and a task half done. Watch the failure once, before writing a retry branch:

curl -i https://moltlinestudio.com/api

That response is the paid step your agent hits mid-run, and it is the one call you must never treat as transient. A dropped connection is a different problem from an entitlement rejection, and both differ from a settlement challenge.

Ordering comes after classification: put the paid step last, or make each step idempotent with an Idempotency-Key header. The IETF draft describes that header as making non-idempotent POST requests fault-tolerant, though it remains work in progress, not a standard.

The only purchase inside a run is a single 19 USDC settlement on Base for a month of All-Access. Idempotency therefore covers one POST, not a stream of per-call charges.

How to reproduce a paid tool call failure before you write retry code

Pick a premium tool and call it with no licence attached. Reproduce the failure before writing any retry wrapper. Moltline's servers need initialize first, so this opens a session on the catalog server and then calls its premium get_full_kit tool with a real kit slug:

EP=https://mcp.moltlinestudio.com/catalog
H='Accept: application/json, text/event-stream'
J='Content-Type: application/json'
INIT='{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"probe","version":"1.0"}}}'
curl -sS -D headers.txt -o /dev/null -X POST "$EP" -H "$J" -H "$H" -d "$INIT"
SID=$(grep -i '^mcp-session-id' headers.txt | awk '{print $2}' | tr -d '[:space:]')
curl -sS -X POST "$EP" -H "$J" -H "$H" -H "mcp-session-id: $SID" -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'
curl -sS -X POST "$EP" -H "$J" -H "$H" -H "mcp-session-id: $SID" -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_full_kit","arguments":{"slug":"kit-developer-starter"}}}'

Expected outcome: HTTP 200 and a normal tool result, not a JSON-RPC error object. Its structuredContent, repeated as JSON in the content text, has "error":"premium_tool_requires_license", an upgrade_url, and an x402 block whose resource is https://moltlinestudio.com/api. It is not HTTP 402. That status belongs to the payment endpoint. The MCP host returns the entitlement code.

Log that error code, never the message text. Retry logic keyed on the message breaks when wording changes. Code-keyed logic does not.

Host matters: mcp.moltlinestudio.com/<server>. There is no mcp.moltlinestudio.com/api. A request sent there returns the wrong failure and teaches you nothing.

See both shapes with your own eyes first: this licence code, then the x402 challenge from the payment endpoint. how HTTP 402 handling differs explains that split.

Next, classify every failure before the loop starts.

Which agent tool call failures should you retry?

Once the code string is in your log, stop treating every error object as one class. Sort each failure into four buckets before the loop starts.

  • Transport: no usable answer arrived. Connection reset, DNS failure, timeout, or a stream cut mid-body. The server may never have seen the call.

  • Request-level: the server understood the call and refused it. Unknown tool name, bad arguments, wrong content type. The same bytes get the same refusal.

  • Entitlement: the tool exists, the call is well-formed, and you hold no licence. premium_tool_requires_license is what a premium tool returns from a host listed in the server catalogue.

  • Payment challenge: the 402 from the payment endpoint. That is a separate class, handled later.

Only transport is a retry candidate. Fix a request-level error, buy a licence for an entitlement error, and settle or stop for a challenge.

If you are unsure how these failures arrive over the wire, MCP transport failure modes shows the shapes.

A wrapper that ignores the code string will retry the unretryable for as long as its cap allows. Classify first, then decide whether the loop runs at all.

Retry decision table: transport, entitlement and payment failures

Classify on the code string first, then read this table. It is our practice, not an IETF or x402 rule. No published source defines which MCP error classes are transient.

Failure class

What it looks like

Retry?

What to do instead

Transport

Connection reset, DNS failure, timeout

Yes

Backoff, cap at three attempts

Server busy

503 or 429

Yes

Backoff and honour any server-sent delay

Entitlement

premium_tool_requires_license from mcp.moltlinestudio.com/<server>

No

Settle 19 USDC on Base for a month at https://moltlinestudio.com/api, or 2 USDC for a day pass at https://moltlinestudio.com/api/premium/day-pass, then call again

Payment challenge

402 returned by https://moltlinestudio.com/api

No

It is a payment instruction, not a hiccup. Settle once or stop

Request-level

Invalid arguments, unknown tool

No

Fix the payload

Rows three and four get conflated constantly. The entitlement code comes from the MCP host; the 402 comes from the payment endpoint. Different hosts, different fixes. RFC 6585 standardises 429 but leaves the retry count to the client, so pick a cap and apply it consistently.

If your client is Claude, the Claude MCP integration notes show where errors surface before your loop sees them.

What does premium_tool_requires_license mean and should you retry it?

That table's entitlement row is the one agents get wrong. premium_tool_requires_license is an entitlement failure: the tool is real, the request is well formed, and the account behind it holds no licence. Waiting changes none of that.

A retry loop here is worse than useless. It burns the run budget. It delays the real fix. It buries the cause under identical errors. The fix is a raise, not a backoff.

The licence is bought monthly, not per call, and payment is crypto only.

Because the term is monthly, the only purchase a run can contain is a single settlement. There is no per-call charge to retry and no partial purchase to unwind, unlike the licensing models that break runs elsewhere.

Treat it as terminal:

  1. Stop the step.

  2. Print the settlement URL.

  3. Let the human or the paying agent decide.

Do not build a silent purchase path into a retry loop.

Why the x402 402 challenge is never transient

The entitlement error is terminal, and the 402 that follows is equally unretryable, for a different reason. Keep them in separate log fields.

A 402 from the payment endpoint is a deterministic document. It states what to pay and how. The challenge does not resolve on its own, so backoff, jitter and attempt caps have nothing to act on.

The agent has two moves:

  • Settle: one 19 USDC transfer on Base.

  • Stop and report.

Any third path is a loop.

Separate the two errors in your logs and your decision table. premium_tool_requires_license comes from the MCP host. The 402 comes from https://moltlinestudio.com/api. Conflating them is the exact bug run ordering prevents, especially once you route calls across multiple servers.

Never point a client at mcp.moltlinestudio.com/api. It does not exist, and the 404 reads like a network fault when it is the wrong host:

# wrong host: 404, looks like a network fault
curl -sS -X POST https://mcp.moltlinestudio.com/api
# payment endpoint: returns the 402 challenge
curl -sS -X POST https://moltlinestudio.com/api

Log the host and status code on every challenge, so a wrong-host 404 is never mistaken for a retry candidate.

Backoff and a cap: how to stop a retry loop

A deterministic 402 rules out the retry loop for payment. The same reasoning holds for transport failures, but only with a cap.

Retry transport only, then cap it: three attempts, exponential base, full jitter, and a wall-clock cap on the whole step. One slow timeout must not stall the run.

for attempt in range(1, 4):
 if time_left() <= 0: raise StepDeadline()
 try:
 return call()
 except TransportError:
 sleep(jitter(2 ** attempt))
 except (EntitlementError, PaymentChallenge):
 raise # premium_tool_requires_license, 402

Note the shape: entitlement and payment codes route straight to raise. No backoff applies to them.

When a response carries an explicit delay, honour it. Jittering past an explicit retry window just repeats the same refusal.

Log attempt number, error code and elapsed time on every try. A cap-out with no trail is indistinguishable from a crash and costs more to debug.

At the cap, fail the step and stop the run. Continuing with partial results turns one recoverable failure into a run whose state nobody can describe.

How do you order a run so a failed payment leaves no half-done task?

A capped loop still fails. Ordering decides what it leaves behind.

Write the step list before you code it. Ordering is cheaper to change in a list than in a live loop.

  1. Every read-only and free step first.

  2. Build output in a staging form with no external effect.

  3. Settle the licence last.

  4. Commit or publish only after settlement confirms.

Settlement goes to the payment endpoint, never to the MCP host:

curl -X POST https://moltlinestudio.com/api \
 -H 'Idempotency-Key: <uuid>'

If a paid step cannot go last, make each earlier step idempotent: the same input replays without a second artefact, message or charge. The same applies to an image generator you wire in as a tool that writes files.

Never place a side effect before the entitlement check. Publishing before you know whether the premium tool will answer produces exactly the half-done state this article is about.

How do you make a paid step idempotent with an Idempotency-Key header?

If settlement cannot go last, idempotency carries the load. The IETF Idempotency-Key header draft exists to make non-idempotent methods such as POST fault-tolerant, which is exactly what a settlement POST is. Treat it as work in progress: draft-07 was published 15 October 2025 and expires 18 April 2026, and the draft itself says Internet-Drafts are inappropriate to cite other than as work in progress.

One key per purchase. Generate it before the first attempt and reuse it on every retry of that same settlement:

Idempotency-Key: 7f3a1c2e-9b04-4d17-8a55-2c6e0f1d3b48

A new settlement gets a new key. A retry never does.

RFC 9110 (STD 97) is the stable reference for what POST means. It is not a retry policy, so read its retry and status-code sections in full before quoting them. Idempotency is your obligation on the client, and your server's obligation if you build one. No hosted server in this setup claims idempotent writes as a feature. Persist the key with the run, since the agent readiness scoring layers treat durable state as its own check.

What still needs a manual check after a failed settlement
What still needs a manual check after a failed settlement

What still needs a manual check after a failed settlement

A settlement that times out after the transfer was broadcast leaves a genuinely unknown state. Ordinal retry design does not reconcile that; a human does.

Keep two artefacts with the failed run:

  • the Idempotency-Key used for that purchase

  • the Base transaction hash

Without them, proving whether the 19 USDC landed means scanning Base by hand.

Re-running the whole job is only safe if steps two onward really are idempotent. If they are not, clean up the staged output before the retry, not after.

If a settled payment does not show up as a licence, check the transaction on Base first, then contact the studio with the hash. First reply comes within 24 hours and confirmed defects are fixed within 30 days, but reconciliation of a stuck settlement is still a manual step today.

Conclusion: retry the transport, never the entitlement, settle last

Manual reconciliation is the exception, not the loop. Three rules cover most runs:

  • Retry transport failures with backoff, capped at three attempts.

  • Never retry premium_tool_requires_license, and never treat the 402 challenge from https://moltlinestudio.com/api as transient.

  • Put the paid step last, or make every step idempotent so a replay is free. One settlement of 19 USDC on Base per run is the only purchase, because the licence is monthly.

Next, run the first section's curl against one premium tool with no licence. Confirm the code string, then add a raise branch for premium_tool_requires_license before any backoff logic.