How would you design a structured error handling strategy for a large microservice codebase?

Define typed domain errors with codes and messages, wrap errors with context at each layer boundary, map to HTTP/gRPC status codes in middleware, and log with full structured context.

Structured error system

Architectural principles

1
Layer errors: domain layer returns domain errors, service layer wraps with context, transport layer maps to protocol codes
2
Wrap at boundaries: fmt.Errorf("operation: %w", err) to build traceable error chains
3
Never expose internal errors (DB errors, stack traces) to external API clients
4
Attach structured context to logs: error code, request ID, user ID, operation name
5
Define sentinel errors for expected cases (ErrNotFound, ErrConflict) and typed errors for recoverable cases with extra data

Difficulty: 8/10

Topics: error wrapping and propagation, structured logging and tracing, error classification and recovery

Scenario Questions

0-2 years experience

1
You're adding a new endpoint that calls a database — if the query fails, how would you structure the error so the caller knows it's a connectivity issue and not a data validation problem?
2
Your service logs an error but the team can't find where it came from — what would you change in your error handling to make debugging easier?

2-5 years experience

1
A feature started failing intermittently in staging — the logs show 'context deadline exceeded' but no stack trace. How would you track down the root cause and improve the error handling?
2
You're building a payment processing flow with three microservices. One service sometimes returns a 429 — how do you handle that differently than a 500, and why?

5-8 years experience

1
Your team has 15 microservices, each handling errors differently — how would you design a unified error strategy that doesn't add latency or bloat, while still enabling SREs to triage incidents fast?
2
You're migrating from plain errors to a structured error type with codes and metadata. What backward compatibility risks do you anticipate, and how do you phase it in without breaking clients?

8+ years experience

1
Your company is scaling to 100+ services, and error volume is overwhelming your observability pipeline — how do you redesign error handling to reduce noise while preserving diagnostic fidelity?
2
You're designing a new platform for internal services — how do you enforce consistent error handling across teams without stifling autonomy, and what metrics would you track to measure success?

Follow-up Questions

❓How do you decide when to wrap an error versus returning it raw?
❓What happens if a downstream service starts returning 500s — how do you prevent cascading failures?
❓How would you test that your error handling actually works in production?