Validating Requests & Returning Errors

What These Terms Mean

Validation: Checking that data meets your rules before you act on it. In our case, we want to ensure a task has a non-empty title under 200 characters. If validation fails, the program stops and reports the problem instead of proceeding.

Error envelope: A fixed JSON shape used for every error response. We will use {"error":"<message>"}. A client only has to learn this one shape to handle every failure your API can produce.

4xx vs 5xx: HTTP splits failures based on who is at fault. A 4xx status means the client sent something wrong, like bad JSON or a missing title. A 5xx status means the server failed unexpectedly, even though the request itself was fine.

Why Validate Before Storing

An empty title is not a valid task. If we store it anyway, every reader of that data inherits a value that never should have existed. This includes the list endpoint, a future search feature, or a human looking at the database. Garbage in, garbage out. Checking the data before it touches the store is the cheapest way to catch mistakes. It also means we never trust a network client with data we can validate for free on our own machine.

Consistency matters just as much as correctness. Before this chapter, a 404 error came back as text/plain, while a successful response came back as application/json. A client written against this API would need a special case for every error path. It would have to read the status code and then guess whether the body is JSON or plain text. Using one {"error":"..."} shape for every failure removes that guesswork. The client can always call response.json() and read the .error field if the status is not 2xx.

Finally, we want to avoid leaking internal details. A database timeout, a nil pointer, or a bug in our code should never turn into a raw Go error string in an HTTP response. That string might mention a table name, a file path, or stack details. This information is none of the client's business, and the client cannot act on it anyway. Instead, we log the real cause on the server and send back a flat, generic message to the user.

The Task Learns to Validate Itself

We will update internal/task/task.go with two sentinel errors, a constant, and a Validate method:

The Validate method uses a pointer receiver, *Task. The strings.TrimSpace function does not just check the title; it rewrites it directly on the receiver. This ensures that " Buy milk " gets stored neatly as "Buy milk". If we used a value receiver, Go would trim a copy of the task and throw the result away.

The method checks two rules in order. An empty title after trimming returns ErrTitleRequired. Anything over MaxTitleLength returns ErrTitleTooLong. Both are ordinary sentinel errors using the errors.New pattern from Chapter 12. In this case, the handler only reads their .Error() string rather than comparing them with errors.Is.

Validation lives on the Task struct itself, not inside the handler. This allows create and update to share one set of rules instead of duplicating the checks. We are writing this by hand so you can see exactly how it works. A larger project would likely use a struct-tag-driven library like go-playground/validator. We skip that here to keep the mechanics visible.

One Envelope for Every Error

Next, we add a small error type and two helper functions to internal/task/handler.go. Every handler will now route its errors through these helpers:

The writeError function is very thin. It wraps a message in an errorResponse struct and hands it to the writeJSON helper from Chapter 17. This guarantees the Content-Type: application/json header is set in exactly one place.

The writeStoreError function maps the store's sentinel errors to HTTP status codes. errors.Is(err, ErrNotFound) becomes a 404. Anything else falls through to a generic 500. We log the real error with log.Printf before hiding it from the client.

Now we update the create handler. It calls Validate() right after decoding the request, before the store ever sees the task:

The flow is simple: decode, validate, then store. If either of the first two steps fails, the function returns before store.Create is ever called. The update handler follows the exact same shape: parse the {id}, decode the body, validate, and then call store.Update. Every failure in both handlers, as well as in get and delete, now goes through writeError or writeStoreError instead of http.Error. There is not a single bare-text error response left in the package.

Trying It With curl

Boot the server the same way as before:

Open a new terminal and try sending an empty title, a valid title, a malformed body, and a request for a task that does not exist:

Every failing request now comes back with Content-Type: application/json and a body shaped like {"error":"..."}. The empty title, the malformed body, and the missing task all share the same response format. They just carry different messages and status codes. The valid POST still returns a 201 status with the full task, unchanged from Chapter 20.

Beginner Mistakes to Avoid

• Leaking the real error string. Calling err.Error() on a database or JSON error can expose file paths, types, or internal details. A client has no business seeing these. Our writeStoreError function logs the real error and sends back a safe, generic "something went wrong" for anything that is not ErrNotFound.
• Using a different error shape per handler. If one handler returns {"error": "..."} and another returns {"message": "..."}, the client code becomes messy with special cases. Route every failure through the same writeError helper to keep things uniform.
• Validating after the store call. Checking the title after store.Create has already written it means you have to undo a write you never should have made. Always validate first, then persist.

What's Next

In Chapter 23, we will split this single task package into distinct handler, service, and storage layers behind an interface. This will allow the storage mechanism to change without touching the HTTP code at all.