微服务内部通信产生的4XX错误如何传递给终端用户？

Great question—this is a super common pain point when building microservice chains, and the right approach balances clarity for end users, security, and maintainability. Let’s break this down:

What to Return to the End User #

First, remember the core rule: 4XX errors signal a client-side problem (invalid input, missing permissions, non-existent resource, etc.). Unlike 5XX errors (which are service failures), you shouldn’t mask this category—instead, you should pass the "client made a mistake" signal clearly, but with context that makes sense for the end user.

• HTTP Status Code: Keep it a 4XX, but align it with the intent of the original error (not necessarily the exact code):
  • If B/C returns 400 Bad Request, A returns 400 Bad Request.
  • If B/C returns 401 Unauthorized or 403 Forbidden, mirror those codes directly (auth errors need clear signals for clients to handle login/permission flows).
  • If B/C returns 404 Not Found, return 404 Not Found—but rephrase the message to fit the client’s request context (not internal service jargon).
• Response Body: Craft a secure, client-friendly payload that includes:
  • A human-readable message tied to the client’s action (e.g., "The email address you provided is invalid" instead of "Service C rejected input: invalid email").
  • An optional application-specific error code (like INVALID_EMAIL or RESOURCE_NOT_FOUND) so clients can programmatically handle the error.
  • Never expose internal service names, endpoints, or stack traces—this is a security risk and confusing for end users.

How to Safely Pass the 4XX Error Through the Chain #

Here’s a step-by-step workflow that works for most teams:

1. Capture the error in Service A: When A receives a 4XX from B (or B receives one from C and forwards it to A), first validate that it’s truly a client error (not a misclassified 5XX from a downstream service).
2. Transform the error for the client:
   • Map the downstream 4XX to the appropriate client-facing 4XX code (as noted above).
   • Rewrite the error message to be client-centric—strip out references to services B/C and internal details.
   • Log the full internal error (including service names, original payloads, and stack traces) for debugging purposes—but keep this server-side only.
3. Return the transformed response: Ensure headers are set correctly (e.g., WWW-Authenticate for 401 errors, Content-Type: application/json for JSON payloads) so clients can parse the response properly.

Example Flow #

Let’s use your chain to make this concrete:

Client sends a request to A with a non-existent user ID.
A calls B with that ID.
B calls C to fetch the user, and C returns 404 Not Found: User ID 999 does not exist.
A logs the full internal error for debugging, then returns this to the client:

{
  "status": 404,
  "error": "Not Found",
  "message": "The requested user could not be found.",
  "code": "USER_NOT_FOUND"
}

Key Best Practices #

• Don’t convert 4XX to 5XX: 5XX tells clients your service failed, but 4XX tells them they need to fix their request—keep this distinction clear.
• Standardize error payloads: Define a consistent format across all your services so clients know exactly what fields to expect (e.g., always include message, code, and status).
• Avoid oversharing: Clients don’t care about your internal service structure—they just need to know why their request failed and how to fix it.

内容的提问来源于stack exchange，提问作者Neel Salpe