Designing Reason Codes for Agent Refusals: A Taxonomy That Scales

Four properties carry the weight.

Actionable. Each code resolves to one action with fixed parameters. CONTEXT_AMBIGUOUS means "re-ask with a clarifying prompt, once." CAPABILITY_TOOL_UNAVAILABLE means "retry with backoff, then escalate if the budget is spent." A code that could mean either is broken.

Mutually exclusive. Exactly one code applies to any given refusal. If a request breaks a policy rule and is also ambiguous, you need a precedence order, stated in the taxonomy, so two reviewers classify it identically.

Exhaustive within scope. Every refusal your agent can produce maps to a code. Gaps show up as a fallback bucket, and a growing fallback bucket is a signal the taxonomy has drifted.

Stable. Codes are identifiers, not sentences. Changing the wording of a human-readable description must never change the code. Version the enum, not the string.

The structured-output literature explains why this matters mechanically. A schema-valid object can still violate domain rules; validation belongs after generation, and a typed contract is what separates a parseable response from a correct one (TrueFoundry). A refusal object is no different: shape is not truth, but without shape you cannot even start checking truth.

Split every refusal into one of three levels. The level tells you where the fix lives, which is what makes the action mapping deterministic.

Policy refusals are the cheapest to handle and the most dangerous to retry. Retrying a forbidden action is at best wasted work and at worst a privilege-escalation pattern. The security framing is blunt: an agent that keeps searching for alternate paths after a blocked request has crossed from recovery into probing (NHI Mgmt Group). Terminate, log, and stop.

Capability refusals are where retries earn their keep. A tool that timed out may succeed on the next call. A tool that does not exist will never succeed, so CAPABILITY_TOOL_UNAVAILABLE needs its own retry budget rather than the general one. Note the failure mode documented in agent benchmarks: in one ReAct-style evaluation, 466 of 513 retry attempts were spent on hallucinated or nonexistent tool names (tianpan.co). Those retries were not recovery; they were the failure wearing a disguise. A distinct code lets you cap them.

Context refusals are repair problems. The input was ambiguous, a required field was missing, or the instructions contradicted each other. Rewriting the prompt or asking a clarifying question is the action. Retrying the identical call is not.

The precedence rule that keeps these exclusive: evaluate policy first, then capability, then context. A request that is both forbidden and ambiguous is a policy refusal, because no amount of clarification makes it allowed.

Two failure modes wreck taxonomies: codes that overlap and codes that are missing.

Overlap shows up as disagreement between reviewers. Give two engineers the same 50 refusal transcripts and see whether they assign the same code. If they agree on fewer than, say, 90%, you have overlapping definitions, not a training problem.

Gaps show up as the fallback bucket. Instrument it. If UNCLASSIFIED exceeds a few percent of refusals, you have a code to add.

The mechanism that prevents both is the typed contract. Define the codes as an enum in a JSON schema so a malformed refusal fails validation at the boundary, not in your router. The structured-output guidance is explicit that native schema enforcement narrows the interface but does not eliminate refusal, truncation, or fallback behavior, so validate on your side too (Agenta). Grammar-constrained decoding nearly eliminates syntax errors but leaves structural and semantic errors intact, which is why the enum helps and still needs a semantic check (arXiv).

{
  "type": "object",
  "required": ["reason_code", "level", "detail"],
  "additionalProperties": false,
  "properties": {
    "reason_code": {
      "type": "string",
      "enum": [
        "POLICY_RESTRICTED_DATA",
        "POLICY_UNAUTHORIZED_ACTION",
        "POLICY_RATE_LIMITED",
        "CAPABILITY_TOOL_UNAVAILABLE",
        "CAPABILITY_TOOL_ERROR",
        "CAPABILITY_KNOWLEDGE_GAP",
        "CONTEXT_AMBIGUOUS",
        "CONTEXT_MISSING_FIELD",
        "CONTEXT_CONFLICTING_INSTRUCTIONS"
      ]
    },
    "level": { "type": "string", "enum": ["policy", "capability", "context"] },
    "detail": { "type": "string", "maxLength": 280 }
  }
}

Reject additionalProperties and free-form codes. A model that invents POLICY_TOO_HARD should fail the contract and route to the unclassified bucket, where you can see it, rather than silently reaching your action table.

The orchestration literature makes the same point at the agent-to-agent boundary: define typed schemas for every handoff so a malformed payload fails validation instead of silently corrupting downstream state, and treat schema violations as contract failures routed to retry, repair, or escalation (MLflow). A refusal is a handoff.

With the taxonomy fixed, the action table is a pure function: code plus attempt count plus budget state in, one action out. Keep it in code, not in a prompt.

The retry path needs its own discipline. Exponential backoff with jitter is the standard prescription: spread retries so many clients do not retry in lockstep, and cap attempts and elapsed time (web-alert.io). PostGrid's documentation of the same pattern recommends retrying up to five times over roughly a 30-minute window with an idempotency key so a retried create does not duplicate (PostGrid).

The subtlety specific to LLM agents is that retries are not free. Agent frameworks commonly retry by replaying the conversation history, so a retry costs the cumulative tokens so far, not one step's worth. On a three-step agent with a 20% per-step retry rate, that pushes token cost to roughly 1.7 to 1.9 times baseline; on a five-step agent, to 2.2 to 2.5 times (tianpan.co). Denominate your retry budget in tokens, not attempts, or a cheap-looking retry rate becomes a doubled bill.

The tri-state distinction matters here too. Confirmed failure (explicit rejection before any state change) is safe to classify and often safe to retry. Indeterminate outcome (a timeout after the request may have been applied) is not a refusal at all; it is an unknown that needs a reconciliation query before any retry (exemplary.ai). If your taxonomy tries to code a timeout as CAPABILITY_TOOL_ERROR, you will retry a write that may already have landed.

A taxonomy is a hypothesis. The fixture set is the test.

Build the fixtures. Collect 100 to 200 refusal transcripts from real traffic, staging runs, and adversarial prompts. Include the boring cases (a tool that returns 503), the policy cases (a request for restricted data), the ambiguity cases (a form with a missing account number), and the nasty ones (a request that is forbidden and ambiguous).

Label them twice. Two people label independently, then reconcile. Disagreements reveal overlapping codes. Write the precedence rule into the taxonomy document and re-label.

Run the classifier. Feed each fixture through the real agent and check two things: that the output validates against the schema, and that it carries the label your team assigned. Track three numbers:

Test the actions, not just the codes. For each fixture, assert that the resolved action matches the table. This catches the case where a code is right but the retry budget is miswired. For retry fixtures, advance a mock clock and confirm the backoff schedule fires and the budget stops the loop; testing retry logic without controlling time is guesswork, which is why controllable failure injection belongs in the fixture harness (SystemDR).

Re-run on every prompt or model change. The refusal distribution shifts when the model changes, and a code that was rare becomes common. Regression-test the taxonomy the same way you test any other output contract. This is exactly the operational discipline implied by treating schema violations as contract failures with explicit retry, repair, and escalation routes (MLflow).

One more fixture class pays for itself: the wrong-looking-but-correct case. An agent that declines a legitimate request because it misread the policy should map to a code that surfaces in a review queue, not to a silent terminate. Otherwise your metrics look clean while users quietly leave.

If you are running agents across several providers, the refusal object is one of the few things that must stay identical everywhere. Quanta Inference puts text, image, video, audio and embedding models behind one OpenAI-compatible API key with prepaid pricing in US dollars (https://quantaintelligence.ai/inference), which means one schema and one action table rather than a per-provider translation layer.

Two practical follow-ons. First, keep the action table outside the model. Whether the model is a frontier reasoning system or a small fast one, the routing decision is deterministic code and should be reviewed like code. Second, when the taxonomy keeps growing because your agents cover more business processes, that is a sign the refusal logic has become a governance artifact, and governance artifacts deserve owners rather than a solo maintainer.

• Every code maps to exactly one action with fixed parameters.
• Every code has a stated level: policy, capability, or context.
• Precedence rule is written down: policy, then capability, then context.
• The enum is enforced by a schema at the boundary and rejects unknown codes.
• The fallback bucket is instrumented and alerted on.
• Retry budgets are denominated in tokens or context, not just attempts.
• Indeterminate outcomes are not coded as refusals.
• The fixture set covers all three levels, plus at least one doubly-qualified case.
• Agreement, unclassified and action-correctness metrics run in CI.