Go Error Design at Scale on Atharva Pandey

Lesson 8: Production Error Architecture — Designing the error system for a real service

Sat, 14 Jun 2025 00:00:00 +0000

This is the lesson where everything comes together. Over the previous seven lessons we’ve looked at sentinels and typed errors, wrapping strategy, error classification, where to log, how to translate at layer boundaries, and when panic is actually defensible. Now I want to show you what all of that looks like assembled into a complete, production-ready error system for a real API service.

I’m going to build the full error architecture for a hypothetical orders API. By the end you’ll have a template you can adapt directly — the error type hierarchy, the middleware, the structured logging, and the client-facing error codes. This is the code I wish I’d had when I started building services in Go.

Lesson 7: Panic, Recover, and When They're Actually Justified — Panic is not error handling

Tue, 13 May 2025 00:00:00 +0000

I’ve seen panic(err) used as error handling more times than I’d like to admit — including in codebases I helped build. The reasoning always sounds logical at the time: “this error should never happen, and if it does, the program state is corrupt anyway, so why not just panic?” The problem is that “should never happen” is a statement about your expectations, not about reality. And “program state is corrupt” is almost never true — one request failed, the other thousand are still fine.

Lesson 6: Error Boundaries Across Layers — Translate at the border, don't leak internals

Sat, 19 Apr 2025 00:00:00 +0000

One of the most subtle security issues I’ve encountered in Go APIs isn’t an authentication bug or a missing authorization check — it’s a SQL error message showing up in a JSON response. Something like {"error": "pq: duplicate key value violates unique constraint \"users_email_key\""}. The frontend is now showing your users your database schema. Not great.

This happens because somewhere between the repository and the HTTP response, someone got lazy with error translation. The raw database error bubbled all the way up and got written directly into the response. Error boundaries exist to prevent exactly this — they’re the translation points between layers, where internal implementation details get converted to appropriate external representations.

Lesson 5: Logging vs Returning — Log at the boundary, return everywhere else

Mon, 17 Mar 2025 00:00:00 +0000

There’s a smell I encounter in almost every codebase I’ve reviewed — including ones I wrote early in my Go career. Someone discovers that err != nil and, out of an abundance of caution, they log it right there. Then return it. Then the caller logs it again. Then the middleware logs it a third time. By the time a single failed database query reaches the response, it’s appeared in the logs four times with slightly different messages and you can’t tell whether four things failed or one thing failed four times.

Lesson 4: Operational vs Domain Errors — Not all errors deserve the same treatment

Fri, 28 Feb 2025 00:00:00 +0000

One of the more expensive lessons I learned was treating all errors the same. When a database connection drops, you retry. When a user sends an invalid email address, you return a 400 and explain what’s wrong. When someone tries to access a resource that doesn’t belong to them, you return a 403. These are completely different situations — different causes, different remedies, different communication needs — and collapsing them into a single err != nil branch produces services that retry permanent failures, expose internal details to users, and log noise that drowns out real alerts.

Lesson 3: Wrapping Strategy — Every wrap should add context, never noise

Tue, 04 Feb 2025 00:00:00 +0000

There’s a certain kind of error message I’ve come to dread in production logs: auth: db: sql: connection refused. Technically, it contains the full path from the handler down to the socket. Practically, it tells me nothing I couldn’t figure out from the stack trace — and it takes ten seconds to parse. That error message is the output of wrapping done wrong: every layer added its name reflexively, without thinking about what the reader actually needs.

Lesson 2: errors.Is and errors.As — Matching errors through the wrapping chain

Thu, 09 Jan 2025 00:00:00 +0000

Go 1.13 shipped what I consider the most important error-handling improvement the language has had: errors.Is, errors.As, and the %w verb. Before that, wrapping errors with context meant breaking the ability to inspect them. You’d wrap with fmt.Errorf("context: %v", err) and then the original error was gone — you could log it, but you couldn’t match it. Callers would resort to string matching or just give up and let every error map to a 500.

Lesson 1: Sentinel vs Typed Errors — Know your error before you handle it

Sat, 14 Dec 2024 00:00:00 +0000

When I first started writing Go seriously, I treated errors like fire: try to avoid them, and when you can’t, put them out as fast as possible with an if err != nil { return err }. It took a few production incidents — and a lot of reading other people’s codebases — before I understood that errors aren’t just signals. They’re data. And how you design that data determines how well your callers can respond to failures.