Scenario 4: Missing Standard Error Envelope
Scenario Summary
One service returns a raw exception payload while others return a structured response envelope. The frontend or downstream consumer expects a stable shape, crashes on the unexpected payload, and turns a recoverable backend error into a user-facing session failure.
Why It Matters
Standardized components are not only about internal convenience. They protect every caller from variation in backend behavior.
Failure Pattern
| Platform area | Weak choice | Better choice |
|---|---|---|
| Response contract | Each service invents its own success and error shape | Shared envelope for every response |
| Validation | Trust services to serialize correctly | Validate envelope before sending to clients |
| Consumer logic | Parse fields loosely or optimistically | Strong contract checks and graceful fallback |
Deep Dive
Error-envelope drift is dangerous because it often appears only during failure conditions. That means the contract is least tested when reliability is already under pressure. A good standard envelope should make it obvious:
- what kind of message this is,
- whether the error is retryable,
- which request it belongs to,
- which service produced it.
Detection Signals
- Frontend runtime errors spike during backend failures
- Retry logic does not trigger because expected fields are missing
- Different services produce incompatible error payloads for similar incidents
Runbook
- Define a single response envelope for success, stream, and error events.
- Share the schema between backend and frontend.
- Add validation before responses reach the transport layer.
- Wrap unhandled exceptions in the standard error envelope.
- Test failure cases, not only happy-path responses.
Questions To Ask
- What fields must every response include, even during failures?
- Which error fields do clients need for safe retries or user messaging?
- Where should envelope validation happen?
- How will we roll out breaking contract changes?
Interview Drill
Why do error contracts usually need more design discipline than success responses in GenAI systems?
Good Outcome
Every service emits the same response envelope, consumers remain stable during failure scenarios, and contract violations are caught before they reach users.