Recovering from a refusal

A splicedeck refusal is a successful call that carries its own correction. It is not an error to report and not a wall to work around. Ninety-four codes exist so that recovery is one turn rather than a diagnosis.

The full catalogue, generated from the code, is in references/refusal-codes.md. Read it when you need a specific code. The four rules below are what you need every time.

The four rules

1. When retry_with is non-empty, send one of those calls verbatim.

The server built them from what it already knows — the handles that exist, the bookmarks that are shipped, the rung that is proven. Re-deriving the arguments yourself turns a one-turn recovery into a guessing loop, and you will get it wrong in exactly the places the server would not.

{"ok": false, "refused": "SHEET_NOT_VERIFIED",
 "retry_with": [{"verb": "verify", "args": {"sheet": "c1"}}]}

Send verify(sheet="c1"). Do not construct something similar.

2. When needs_human is true, stop and report human_step.

No call you can send fixes it. Saying so plainly is the correct outcome. Inventing a workaround here is worse than stopping, because the workaround usually means disabling the thing that refused.

3. Never install anything in response to a refusal.

FFMPEG_ABSENT does not mean "go and get ffmpeg". This project never installs, downloads, vendors or bundles ffmpeg — that is a deliberate rule, not an omission, and docs/first-run.md §4 gives the three reasons. The same holds for TIER_BINARY_ABSENT. Report the step; the human runs it.

4. A refusal is not a reason to change the plan.

Most refusals mean one call is missing, not that the approach is wrong. Add the call and continue.

The ones you will actually hit

Reading the envelope

{"ok": false, "verb": "deliver", "refused": "CODE",
 "plain": "one sentence, at most 160 characters",
 "retry_with": [{"verb": "…", "args": {…}}],
 "needs_human": false,
 "human_step": "present only when needs_human is true",
 "spent": {"class": "heavy", "ms": 13}}

On MCP the envelope is in structuredContent and isError is false — a refusal is deliberately not a JSON-RPC error, because hosts flatten protocol errors to a string and the model would then see the sentence and never retry_with.

On the CLI the envelope is on stdout and the exit code is 1.

Three fix classes

Every code is one of three, and the class tells you what to expect before you look.

• always — a machine fix always exists, so retry_with is never empty. If you see an empty one on an always code, that is a bug worth reporting.
• sometimes — check retry_with; it may be empty depending on state.
• human — needs_human is true. Rule 2.

When retry_with is empty and the class is always

That is a defect, not a puzzle. It has happened: five construction sites once passed a dict where a tuple of calls belonged, so callers received the strings ["verb", "args"]. If you see it, say so rather than guessing at the arguments — the guess will look like it worked and will not be what the server meant.