Error messages

When your fallback ladder fires, somebody sees something. What they see decides whether your system feels trustworthy-but-occasionally-busy or flaky-and-dishonest. Error surfaces have three audiences with three different needs — write for each.

For operators (the human in the queue)

The support agent receiving a routed email needs context, not apology: what the system concluded, why it stopped, and where to start.

⚠ Routed for review — confidence LOW
Best guess: RETURN_REQUEST (2 of 3 runs; 1 run said COMPLAINT)
Why routed: damage words present in a FORWARDED message — ownership unclear
Model's draft reply: attached (unverified)
Start here: confirm whether the damage report is the sender's own order

• Lead with the best guess and the disagreement — the operator's job shrinks from 'read everything' to 'resolve one named ambiguity'.
• Say why it was routed in task terms, never in mush ('an error occurred').
• Mark machine work as unverified so nobody forwards the attached draft unread.

For end users (the customer)

• Honest about state, silent about plumbing: 'We've received your message — a member of our team will reply within 4 hours.' No 'our AI had low confidence', no fake 'we're reviewing your case personally' if nobody is yet.
• Never let a failure message promise what the failed system was supposed to deliver. The classic sin: an auto-reply that says 'we've processed your return' generated by the very pipeline that just failed to process it.
• Give a real next step — a timeframe, a link, a reference number. An error message without a next step is just an apology.

For the log (future you)

Every failure log line carries: input (redacted), prompt version, model + settings, which validator or signal fired, retry transcript, final route. Two of those get forgotten constantly — prompt version (you can't reproduce a bug against a prompt you can't identify) and the retry transcript (the difference between 'failed once, recovered' and 'failed identically twice' is diagnostic gold). Your weekly review reads these logs and feeds the golden set: failure → case → fix → eval. The flywheel, closed.