Unit 09.04: Error messages that tell the user what to do

The error message is what the user acts on, and five different states should not share one.

Distinguishable, and free of internals

Five states with a distinct message each.

The code prints them.

MESSAGES = {
    "rate_limited": "Busy right now -- try again in a moment.",
    "provider_down": "The assistant is unavailable. Here is the source document.",
    "bad_input": "That file could not be read. It must be UTF-8 text under 4,000 characters.",
    "filtered": "That request could not be processed.",
    "no_answer": "The documents do not cover that.",
}
for state, message in MESSAGES.items():
    print(f"{state:15} {message}")

print("""
Two rules. Each message must be distinguishable, so the user knows whether to
retry, fix their input, or come back later -- "something went wrong" for all
five wastes their time on whichever guess is wrong.

And none of them should include the exception, the model name or the prompt
version. Those go in the log, indexed by a request id the user can quote.
""")

Each message tells the user what to do next: wait, fix the input, look elsewhere, or come back later. "Something went wrong" for all five wastes their time on whichever guess is wrong.

None of them contains the exception, the model name or the prompt version. Those go in the log, indexed by a request id the user can quote in a report.

The mistake this prevents

The mistake is surfacing the provider's error text directly. It leaks your model choice and configuration, it is written for a developer, and it changes without notice when the provider updates.

Takeaway

Write the failure messages as a set, check no two are confusable, and keep internals out of them. Give the user a request id instead.

Mark complete