Error Handling in Go REST APIs: From Boilerplate to Beautiful

Parastesh — Mon, 07 Jul 2025 07:42:50 +0000

When building REST APIs in Go with frameworks like Fiber, Gin, or Echo, error handling looks simple—until your app grows. Mapping database and validation errors to proper HTTP responses quickly descends into a swamp of repetitive code, scattered switch statements, and too many custom error variables. Here’s my journey from manual error plumbing to a clean, centralized solution.

Approach 1: Layered Error Handling — Clear, but Awkward

My first pass looked “proper”—each layer (repository, service, controller) defined errors, wrapped or mapped them up, and finally each endpoint mapped to HTTP codes.

Repository:

var ErrNotFound = errors.New("not found")

func (r *Repo) FindUser(id int) (*User, error) {
    // ... DB logic
    if notFound {
        return nil, ErrNotFound
    }
    return user, nil
}

Service:

var ErrUserNotFound = errors.New("user not found")

func (s *Service) GetUser(id int) (*User, error) {
    user, err := s.repo.FindUser(id)
    if err == ErrNotFound {
        return nil, ErrUserNotFound
    }
    return user, err
}

Controller:

func (h *Handler) GetUser(c *fiber.Ctx) error {
    user, err := h.service.GetUser(id)
    if err == ErrUserNotFound {
        return c.Status(404).JSON(fiber.Map{"error": "User not found"})
    }
    if err != nil {
        return c.Status(500).JSON(fiber.Map{"error": "Internal error"})
    }
    return c.JSON(user)
}

Why this goes wrong:

Switches and if blocks repeat everywhere.
Adding a new kind of error means updating every layer.
App logic gets buried in error handling code.

Approach 2: Chain of Responsibility — DRYer, Still Boilerplate

To fix duplication, I moved error mapping into a chain of handlers—each responsible for their error type. (Using chain of responsibility pattern)

Example handler:

type ErrorHandler interface {
    Handle(err error) (*AppError, bool)
    SetNext(next ErrorHandler)
}

type NotFoundHandler struct {
    next ErrorHandler
}
func (h *NotFoundHandler) Handle(err error) (*AppError, bool) {
    if errors.Is(err, ErrUserNotFound) {
        return &AppError{Code: 404, Message: "Not found"}, true
    }
    if h.next != nil {
        return h.next.Handle(err)
    }
    return nil, false
}
func (h *NotFoundHandler) SetNext(next ErrorHandler) { h.next = next }
func NewErrorChain() ErrorHandler {
    chain := &NotFoundHandler{}
chain.SetNext(&ValidationHandler{})
chain.SetNext(&DefaultHandler{}) // ... etc

    return chain
}

Using the chain:

user, err := repository.GetUser(id)
if err != nil {
chain := NewErrorChain()
repositoryError := errHandler.Handle(err)
    return repositoryError
}
return c.JSON(user)

This improved things:

Error mapping was reusable and composable.
Handlers were easy to test.

But:

You still set up the chain for every endpoint.
Most of the time, everyone used the same error-handler chain.
Error responses were handled in the controller, cluttering its main logic.

Approach 3: Central Error Middleware — Simple & Scalable

Why Middleware Wins
Eventually, I realized—error mapping is cross-cutting!
The controller should focus on business logic, not error->HTTP mapping. If all errors can be mapped centrally after the handler returns, the controller is blissfully unaware.
You just write a middleware that looks for errors from handlers and returns a consistent response.
Here’s how to do it in Fiber, Gin, and Echo.

Shared Error Mapping Function.
Let’s use a shared function in all three examples:

Fallback Controller:

// AppError represents an HTTP error
type AppError struct {
    Code    int
    Message string
}

func mapErrorToAppError(err error) *AppError {
    switch {
    case errors.Is(err, ErrUserNotFound):
        return &AppError{Code: 404, Message: "User not found"}
    case errors.Is(err, ErrValidation):
        return &AppError{Code: 422, Message: "Invalid input"}
    default:
        return &AppError{Code: 500, Message: "Internal server error"}
    }
}

Fiber

func FallbackMiddleware() fiber.Handler {
    return func(c *fiber.Ctx) error {
        err := c.Next()
        if err == nil {
            return nil
        }
        appErr := mapErrorToAppError(err)
        return c.Status(appErr.Code).JSON(fiber.Map{
            "error": appErr.Message,
        })
    }
}

Usage:

api := router.Group("/api")
api.Use(FallbackMiddleware())

Controller:
func (h *Handler) GetUser(c *fiber.Ctx) error {
    user, err := h.service.GetUser(id)
    if err != nil {
        return err
    }
    return c.JSON(user)
}

Gin
Gin makes this elegant with its built-in error context and global middleware system.

func ErrorMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        c.Next() // Process handler

        err := c.Errors.Last()
        if err == nil {
            return
        }
        appErr := mapErrorToAppError(err.Err)
        c.JSON(appErr.Code, gin.H{"error": appErr.Message})
    }
}

Usage:

r := gin.Default()
r.Use(ErrorMiddleware())

Controller:
func (h *Handler) GetUser(c *gin.Context) {
    user, err := h.service.GetUser(id)
    if err != nil {
        c.Error(err) // Just attach error to context
        return
    }
    c.JSON(http.StatusOK, user)
}

Echo

Echo middleware completion is equally clean:
func ErrorMiddleware(next echo.HandlerFunc) echo.HandlerFunc {
    return func(c echo.Context) error {
        err := next(c)
        if err == nil {
            return nil
        }
        appErr := mapErrorToAppError(err)
        return c.JSON(appErr.Code, map[string]string{
            "error": appErr.Message,
        })
    }
}

Usage:

e := echo.New()
e.Use(ErrorMiddleware)

Controller:
func (h *Handler) GetUser(c echo.Context) error {
    user, err := h.service.GetUser(id)
    if err != nil {
        return err // Let the middleware map the error
    }
    return c.JSON(http.StatusOK, user)
}

Conclusion: Less Code, Fewer Bugs, More Focus

After all my experiments, middleware-based centralized error handling is by far the cleanest, most maintainable solution I’ve tried for Go APIs.
Repositories, Services and Controllers: Only return errors.
Middleware: Decides response logic in one place.
Easy to add, test, and extend.

Test Driven Development(TDD) as a Junior Back-End Developer (part1).

Parastesh — Tue, 20 Feb 2024 14:54:29 +0000

This article is about my experiences with TDD and a guideline I created for myself. It's my personal path from fearing writing tests to writing every feature using TDD.

What This Document Does Not Cover:

The definition of TDD
Types of tests
Tools for writing tests
Mocking, faking, etc. (to be discussed in Part 2)
Third parties or other services being used in the service you want to test which needs to be mocked.

I had several questions at first. I still do, but they are not stopping me now. I couldn’t even write a single word.

Where should I start? What should I write when a test file is in front of me, waiting for me to type my code?

Which type of tests should I use?

How should I write the scenarios?

How can I predict how I am going to write the feature?

Seeking Inspiration from Examples

I tried to see as many samples as I could to form an initial picture in my mind about tests.

Writing Scenarios

Cost (which includes time) is one of the most important factors while writing code. That is one of the reasons we write tests. But "you have to choose your battles" instead of battling with everything. So, you must make an equilibrium between time and quality by choosing a suitable test type.

At this point, I didn’t know whether to choose Unit Tests or Feature Tests. A Feature Test, for example, for creating a user is a single path starting from a route (localhost:8000/user/create) to the logic until the user is being created successfully or not.

What I am dealing with mostly are CRUDs. Using TDD for most of the CRUD codes needs Feature Test.
Drafting Test Scenarios
You are facing a new task. You may have no idea how you want to write the code. Start with what is almost obvious: The Feature. Creating a user, updating a price, deleting an order, getting a list of foods.

Write what you expect:

It can create a user.
It can update the price.
It can delete an order.
It can get a list of foods.
They may also fail too, right? Look for the failing conditions.

It cannot create a user with an existing phone number.
It cannot update the price with an invalid price format.
...
Voila! You have your scenarios. For the format, check the team and framework conventions.

Write the scenarios in your test file as methods with no content.

laravel example:

Detailing Your Tests

Now that you have your scenarios, it is time to write the test contents. Slow down here a little bit if you have a challenge like I did. You are writing a path (Feature Test).

Write the beginning and ending points first. The beginning point is the route; the ending point is the response, whether it is an HTTP status code or content.
Well, you have come to the main part of the road.

Identifying Prerequisites

Now, you must see what the prerequisites are. It can be a pre-created user (for failing tests of creating a user, for updating a price or for deleting an order) or a pre-created product you want to update its price.

You successfully have failing tests! It is time to pass these tests. You may face the need for making changes that may affect your code; change the test first.

Keep this cycle:
Write the test that fails, write the code that passes the test.

That’s it! I would be happy to read your experiences too.

DEV Community: Parastesh

Error Handling in Go REST APIs: From Boilerplate to Beautiful

Approach 1: Layered Error Handling — Clear, but Awkward

Approach 2: Chain of Responsibility — DRYer, Still Boilerplate

Approach 3: Central Error Middleware — Simple & Scalable

Conclusion: Less Code, Fewer Bugs, More Focus

Test Driven Development(TDD) as a Junior Back-End Developer (part1).

What This Document Does Not Cover:

Seeking Inspiration from Examples

Writing Scenarios

Detailing Your Tests

Identifying Prerequisites