Error codes, refusal verdicts and what each one actually means

Every attempt to answer writes a row to ai_support_turn — including the ones that produced no text at all, because why did the assistant stay silent is the question operators actually ask. That row carries four fields worth reading, and this page is what each value means.

Where to read them

Live Inbox → the case pane → Evidence tab. The AI activity list shows the last eight turns: the verdict (falling back to the status), skipReason, escalationReason, retrieval confidence, groundedness, latency, model and cost.

errorCode is returned by the session route but is not drawn in that list. For the code itself, read the backend log — every failure logs one line in this shape — or query the column:

Generation failed for <ticketId> [NO_BACKEND] via mashdiv: <message>

SELECT createdAt, status, verdict, skipReason, escalationReason,
       errorCode, LEFT(errorMessage, 200) AS errorMessage, costUsd
  FROM ai_support_turn
 WHERE ticketId = :ticketId
 ORDER BY createdAt DESC;

Four fields, four different questions

Statuses

SUCCEEDED is the one that misleads. It means the model produced text, not that a customer read it. A turn withheld by the groundedness gate, a copilot draft awaiting a human, and an answer a barge-in stopped from being appended are all SUCCEEDED with wasSent: false — except that when aiSupportDraftOnBargeIn is off, the barge-in turn is moved to CANCELLED instead. The text is still on the row; the status is what keeps it out of the console's draft panel. The provider had already been paid for it, and that cost counts against your caps like any other — a CANCELLED turn is withheld from the agent, not refunded to you.

STREAMING is the one you will never see. The provider is still driven in streaming mode, but the tokens are held: the post-filters that catch an invented link, a refund promise or an ungrounded claim can only run on the finished text, so nothing is put in front of the customer until they pass. The approved answer is released as one frame. A turn therefore goes from PENDING to its final status with no intermediate row state, and a customer who was promised a refund by a draft that was then discarded never read it.

Verdicts

A crypto support agent trips cyber-category safeguards on entirely legitimate questions — "someone accessed my account", "is my seed phrase safe" — so REFUSED is a normal operating state, not an exception. It arrives as HTTP 200 with a possibly empty content array, which is why the refusal flag is checked before the text is ever read. The conversation escalates as forbidden_topic.

skipReason, decoded

A refusing rule writes the bare value rule. The rule's name is not recorded on the turn, so do not go looking for it on the row — which of your rules matched has to be worked out from their patterns on the Agents screen.

not_owner carries the state on the row precisely because the bare value is the least useful reason in the addon — the three causes need completely different responses:

The third is the one to watch. Which escalation reasons the assistant may take back is in Escalation and handover.

unpriced_model — a ceiling that cannot be measured is refused, not assumed safe

"Cost unknown" and "cost nothing" are not the same number, and the caps used to treat them as one. The compatible-endpoint adapter reports no cost by design — it cannot know whether the endpoint behind it is a free local model, a metered API or a flat subscription — and any model missing from the price table reports the same. Both land on the turn row as 0, so an install answering thousands of tickets through a metered endpoint read $0.00 spent for ever and its daily ceiling never fired.

So the gate now counts them. A turn is unpriceable when it moved tokens and recorded no cost; tokens are the discriminator, because a skipped turn, a refusal before the call and a direct answer from one of your own articles all legitimately cost nothing and all move nothing. If either cap is above zero and the current month holds even one unpriceable turn, the gate refuses:

• The turn records SKIPPED / unpriced_model and the session moves to AI_SUSPENDED.
• The whole desk is notified — "AI support paused: spend cannot be measured" — with the number of unpriced calls and both ways out, because "raise the cap in Settings" is useless advice for this one.

Two ways out, and both are decisions only you can make:

1. Price the endpoint. Set AI_SUPPORT_OPENAI_INPUT_USD_PER_MTOK and AI_SUPPORT_OPENAI_OUTPUT_USD_PER_MTOK to what your endpoint charges, in USD per million tokens, and restart. Both are required — half a rate card is treated as none.
2. Set both caps to 0. Zero has always meant "no ceiling", and it is the honest answer for a local model that really is free. An install with no cap never reaches this gate.

Error codes

Two codes read identically as prose — it did not answer — and are completely different problems.

The difference in behaviour matters as much as the label:

A missing key is a configuration state, not an incident, so it does not fill your queue with handovers. A gateway failure is an incident, and the customer must not be left watching a typing indicator, so it goes to a person.

The operator-policy gate

The retrieval floor catches "we have nothing on this subject". It does not catch "we have plenty on this subject, none of it written by this operator" — measured at confidence 0.80 for "what are your withdrawal fees", answered confidently from a chain-specific documentation page belonging to somebody else's install.

So five topics can only ever be answered from an article you wrote:

fees · limits · processing_time · countries · refunds

The test at that gate is the source, not the score. A high-confidence retrieval from the shipped documentation fails it, deliberately, and records operator_policy_undocumented:<topic>.

The customer does not get an eleven-word brush-off. On a policy refusal they are told why there is no single answer and where the real one lives, with no number in it: "fees depend on the currency and the network you're using", "you'll see the exact fee on the Withdraw page before you confirm it". The page is only offered when the route catalogue says it exists on this install.

The translation stop

Settings → Retrieval. With it off, behaviour is byte-identical to an install that never had the feature — and the language check still runs, because turning translation off does not stop non-English customers writing in. A non-English question is marked as such and the policy gate refuses anything it cannot classify, which is where language_not_classifiable:unknown_language comes from.

With it on, a non-English question is rendered into English on the cheap model before retrieval, because the corpus is English and BM25 matches words: a Spanish question shares almost no tokens with any passage, falls under the retrieval floor, and escalates for a question the documentation answers perfectly.

When that translation fails, the turn stops. skipReason: translation_unavailable, verdict ESCALATED, reason no_documentation.

It does not degrade and carry on with the original text, and the reason is the gate above: the same English rendering is what lets the policy gate read the question at all. Continuing would mean answering a question no gate in the system was able to read.

Once a translation succeeds, the strict posture is dropped — with a proper English rendering, "no policy topic" is a real answer rather than an absence of one. Leaving it on would escalate every ordinary non-English question, "where is my deposit" included, on any install without operator articles. That is not a safety gate, it is an outage.

citationMode — and why groundedness reads differently per provider

An OpenAI-compatible provider has no native citations. Documents are numbered in the prompt, the model is required to mark each factual sentence, and the markers are then extracted and range-checked — a model that types [9] when six documents were sent has invented the citation, and clamping it to [6] would attach a real URL to a claim that document does not support. The turn records MARKER, and the customer sees a heading rather than a verbatim quote, because showing a fake verbatim quote would be worse than showing none.

This changes how groundedness reads. The score is per-sentence coverage: what share of factual sentences a citation actually reaches. Under NATIVE that is span overlap; under MARKER it is whether the sentence contains a marker; with neither, it falls back to a ratio, which is all that can be said.

aiSupportGroundednessFloor defaults to 0.4, and that number was re-calibrated when the metric changed meaning. Measured after the change: a well-sourced answer about enabling two-factor authentication came back with four native citations and scored 0.43, because a support answer is mostly procedural prose — "open the app", "scan the code" — and only some of those sentences sit inside a cited span. At the old floor of 0.6 it was withheld and the customer got a handover instead of the answer, at a cost of $0.25.

An answer that asserts facts with nothing behind it scores 0 and is refused at any floor above zero.

The effort parameter and the small fast model

aiSupportEffort says how much deliberation a question deserves. It reaches the managed connection on every call; on your own key it is omitted for any model that rejects it — the cheapest tier does, with a 400, and so does any model the pricing table does not recognise. Omitting it costs default behaviour; sending it to a model that refuses it costs the whole turn, so the adapter drops it rather than gambling.

That distinction matters most on the internal models. aiSupportRerankModel and aiSupportClassifierModel both default to the small fast tier (mashdiv-lite, against mashdiv-core for answering), and they run on reranking, triage and the handover brief — three calls per conversation that nobody reads directly and that would otherwise dominate the bill.

Two related facts from the same adapter, in case you are debugging a 400 yourself:

• No temperature, top_p or top_k is sent, anywhere. The current top-tier models reject all three. Tone is a prompt concern.
• Citations and structured output cannot be combined — that pairing is a 400. Which is why every machine-readable decision the agent makes comes from a tool call rather than a response format.

aiSupportMaxTokens defaults to 4,000 because extended thinking tokens count against it: a smaller ceiling can be consumed entirely by thinking and return empty content. That is a default, not a floor — the field accepts 1,024 to 64,000, on the settings screen and in the backend coercer alike, so nothing stops you saving a value low enough to have answers cut off mid-sentence and thrown away unsent. If you lower it, lower it a little and watch. (The own-key adapter's hard minimum is 1,024, so 1,024 is the real floor everywhere.)

Test connection

It is not a string check and not a ping. It runs the whole path a customer's question takes, and ok is false unless the generation step succeeded — because that is the step that corresponds to a customer actually being answered. A green tick over a mute assistant is a state this endpoint used to report as success, and a buyer whose first impression is that does not file a bug.

What it actually reports

There is no three-valued verdict. Each step comes back as a tick or a cross with a sentence of detail, and the screen draws them as a list under the summary line. The steps are not the same on every provider:

Only the managed connection has a middle step, because it is the only one with something to ask: /v1/account returns your plan, balance and remaining spend cap, and the detail line prints all three. That is the check that separates the gateway wallet is empty from the credential is wrong — on the other two providers both arrive as a failed Answering step and you read the detail to tell them apart.

What the details actually say, so you know what you are looking at:

A failed step short-circuits the ones after it, so the last line in the list is the one to read.

Two more things about it worth knowing:

• It spends money, and the spend is recorded. It performs a real generation, returns costUsd, and files a row against the same ceilings a customer's answer counts against — including when the probe fails, because a failing probe still ran the generation that billed and is the one an operator presses again immediately. It is refused with a 429 when a cap is already reached: there is no point learning the provider works if the budget will not let it answer anybody.
• Read the step, not the summary. The steps that pass before the failing one are exactly why a single "Connected" was so misleading.

Related: Escalation and handover for what each escalationReason means, Troubleshooting for the symptom-shaped version of this page, Provider for the .env variables, and Cost and budgets for what a turn costs.