When the shared failure factory is handed a thrown exception, what should it put in the client-facing message field?

The shared factory is the last piece of code that touches a failure before it becomes bytes on the wire. That position makes it the only place where the question 'what does the client get to see?' has a single answer, and the answer that scales is **default-deny**: the body contains what you deliberately put there, and the thrown object contributes classification only. ## Two sources of text, only one of them yours | Source | Who wrote it | Safe as client-facing text | |---|---|---| | A message attached to your error code | You, for this audience | Yes | | A message on a domain failure your code raised | You, but review the audience | Usually, if written for callers | | The message on a framework or runtime exception | The framework's authors, for developers | No | | The cause chain and stack trace | The runtime | No | The middle row is where teams get sloppy. A domain failure whose message reads *user 4471 has no active subscription in tenant 88* was written for a log line, not for a stranger. Owning the text does not by itself make it audience-appropriate; the factory should render from the code, and any text meant for the caller should be authored as part of the code's contract. ## The mechanism, step by step 1. **Classify.** The factory receives the failure and resolves it to one of your error codes. Recognised failures map to their code; anything not recognised maps to one generic code. 2. **Render from the code.** The client-facing message is looked up for that code. It is stable text, reviewed like any other part of the contract, and it does not vary with the incident. 3. **Attach declared detail only.** If a failure carries structured detail the caller genuinely needs, it travels in a declared place in the envelope with a declared shape - not as prose interpolated into the message. 4. **Log the rest.** The exception's own message, its cause chain and its stack go into the log record for this request, carrying the correlation id that the body also carries. That is the link that makes the stripped body workable rather than merely safe. 5. **Default branch is generic.** An unrecognised failure produces the contract shape with the generic code and message. This is the branch that fires for the failures nobody anticipated, which is exactly when the exception text is most likely to be revealing. ## Why the single write path is what makes it enforceable A rule that says 'do not put exception text in responses' is unenforceable across a hundred handlers. A factory whose message field is simply **never wired to the exception's text** is enforceable by construction: there is one function, it has one expression producing the message, and that expression reads a code-to-message lookup. Reviewing this is reading one function. Testing it is provoking an unmapped failure with a deliberately loud message and asserting that the message does not appear in the body. The same argument applies to everything else the payload might leak - internal identifiers, the name of the component that failed, the count of rows a query returned. If it is not assembled at the single write point, it cannot be in the body. ## The support workflow that replaces the detail The objection to a generic body is always the same: *now nobody can debug it*. The answer is that the detail did not disappear, it moved. The client holds the correlation id; the log record holds the exception text, the stack, the request attributes and the timing, indexed by that id. A support request becomes 'quote the id', and an engineer resolves it in one query. That workflow is what buys you the right to strip the body, and it is worth stating explicitly in an interview, because a candidate who strips the body without building the lookup path has made the system harder to operate rather than safer. ## Edges worth knowing - **Validation detail is not exception text.** Structured information about which inputs were unacceptable is authored content for the caller and belongs in the declared place in the envelope; it does not arrive by copying a thrown object's prose. - **Environment switches are a trap.** A mode that includes stack traces in responses is only as good as the confidence that it is off in every environment that faces a real caller, and that confidence is a deployment property, not a code property. - **A generic message per code beats one per incident.** Resist the urge to make the message helpful by interpolating the specifics; the specifics are the thing you are choosing not to send, and the correlation id is how the caller gets them. - **The unrecognised branch still needs the full contract.** Code, message, correlation id: a generic failure is not an excuse to emit a shape the client cannot parse.