Code-Memo

Error Handling

Standard error response structure

1. Use one envelope everywhere: e.g. { "error": { "code", "message", "details", "requestId" } }.
2. Codes are stable machine strings (order_not_found); messages can change for humans.
3. Include field-level errors for validation (details: [{ "field": "email", "issue": "invalid" }]).

Meaningful error messages

1. Tell the client what to do next without leaking secrets or internal stack traces.
2. Avoid vague “Something went wrong” for 4xx; be specific enough to fix the request.
3. For 5xx, keep user-facing text generic while logging rich context server-side.

Error codes vs HTTP status confusion

1. HTTP status describes transport-level outcome; body code describes domain outcome.
2. Do not return 200 OK with { success: false } for failures; intermediaries and clients will mis-handle it.
3. Align retry behavior: 429/503 may retry; 400/404 usually should not blindly retry the same payload.

Debugging-friendly responses

1. Always return a request/correlation id clients can quote in support tickets.
2. In non-prod, optional debug blocks help; gate them strictly in production.
3. Log the same id across services for distributed traces.