👋 Hey {{first_name|there}},
A strange thing happens in many systems. Two services talk to each other; they are both well written, and still, the integration feels chaotic. Clients do not know which errors deserve a retry. APIs invent a new status code shape for every feature. Support tickets say the same vague line that you have seen before. Something like it failed again. Please try later.
I used to think this was just about better code. It rarely is. It is about the language your services use when they fail. If the language is random, everything downstream becomes guesswork. If the language is clear, even simple clients behave well. The system starts to feel steady. Not perfect, yet steady.
Today is a practical pass at that language. We will write an error contract that sits next to each service and becomes the rule everyone follows. It is one page. It connects to earlier issues in a very direct way. Timeouts and retries only make sense if errors tell the truth. Backpressure needs a clean way to say not now. SLOs and error budgets ask you to be honest about user impact. Dual run compares outputs and needs consistent failure shapes. Even caching is easier when errors are predictable. All of that starts with a small document and a few boring choices that you agree to in advance.
🧭 Mindset shift
From: Every service invents its own error style, and clients guess what to do
To: A simple shared contract where classes of errors carry clear behavior
An error should tell a client what action is safe. Try again with patience. Ask the user to fix something. Do not retry. That is the core idea. If you remember only that, you will already make better choices.
A few small inversions help
• Status codes matter less than semantics. A pretty code that does not guide behavior is not helpful
• Perfect detail in every response is impossible. A short taxonomy used everywhere is better than five exquisite schemas used once each
• Error bodies are for humans and for logs. Error classes are for machines. Keep both, but write them with different goals in mind
• Consistency across teams beats creativity inside one team. Boring is a feature here
🎯 Want to learn how to design systems that make sense, not just work?
If this resonated, the new version of my free 5-Day Crash Course – From Developer to Architect will take you deeper into:
Mindset Shift - From task finisher to system shaper
Design for Change - Build for today, adapt for tomorrow
Tradeoff Thinking - Decide with context, not dogma
Architecture = Communication - Align minds, not just modules
Lead Without the Title - Influence decisions before you’re promoted
It’s 5 short, focused lessons designed for busy engineers, and it’s free.
Now let’s continue.