Error Handling
The most visible difference between a Kori handler and a plain Chi handler is the return type.
// plain Chifunc handler(w http.ResponseWriter, r *http.Request) { ... }
// Korifunc handler(w http.ResponseWriter, r *http.Request) error { ... }Returning errors
Section titled “Returning errors”Return any error from a handler. Kori intercepts it and writes the response.
func getUser(w http.ResponseWriter, r *http.Request) error { user, err := db.Find(chi.URLParam(r, "id")) if err != nil { return kori.NotFound("user not found") } return kori.JSON(w, http.StatusOK, user)}The rules are:
| Returned value | Behavior |
|---|---|
nil |
Nothing — you already wrote the response |
*kori.HTTPError |
JSON response with the error’s status code |
Any other error |
500 Internal Server Error |
HTTP errors
Section titled “HTTP errors”Kori provides constructors for common status codes:
return kori.BadRequest("invalid input") // 400return kori.Unauthorized("missing token") // 401return kori.Forbidden("insufficient permissions") // 403return kori.NotFound("user not found") // 404return kori.Conflict("email already in use") // 409return kori.UnprocessableEntity("invalid data") // 422return kori.InternalServerError("unexpected err") // 500All of them accept an optional second argument for structured details:
return kori.NotFound("user not found", map[string]string{ "id": chi.URLParam(r, "id"),})
return kori.NewError(http.StatusTooManyRequests, "rate limit exceeded", map[string]int{ "retry_after": 60,})Automatic error responses
Section titled “Automatic error responses”When a handler returns a *kori.HTTPError, the default error handler writes:
{ "message": "user not found"}With details:
{ "message": "rate limit exceeded", "details": { "retry_after": 60 }}Unknown errors (anything that is not *kori.HTTPError) produce:
{ "message": "internal server error"}Custom error handler
Section titled “Custom error handler”Replace the default handler with kori.SetErrorHandler. Call it once at startup, before any requests are handled.
kori.SetErrorHandler(func(w http.ResponseWriter, r *http.Request, err error) { var he *kori.HTTPError if !errors.As(err, &he) { slog.Error("unhandled error", "err", err, "path", r.URL.Path) he = kori.InternalServerError("internal server error") }
w.Header().Set("Content-Type", "application/json; charset=utf-8") w.WriteHeader(he.Status) json.NewEncoder(w).Encode(he)})A common use case is RFC 7807 Problem Details:
kori.SetErrorHandler(func(w http.ResponseWriter, r *http.Request, err error) { var he *kori.HTTPError if !errors.As(err, &he) { he = kori.InternalServerError("internal server error") }
w.Header().Set("Content-Type", "application/problem+json") w.WriteHeader(he.Status) json.NewEncoder(w).Encode(map[string]any{ "type": "https://api.example.com/errors", "status": he.Status, "detail": he.Message, })})Wrapping the current handler
Section titled “Wrapping the current handler”kori.GetErrorHandler returns the handler currently in use. Use it to add behavior around the existing one — logging, metrics, tracing — instead of reimplementing the response format:
base := kori.GetErrorHandler()
kori.SetErrorHandler(func(w http.ResponseWriter, r *http.Request, err error) { slog.Error("request failed", "err", err, "path", r.URL.Path) base(w, r, err)})Capture base before calling SetErrorHandler, not inside the new handler — otherwise it would call itself.
HTTPError type
Section titled “HTTPError type”type HTTPError struct { Status int `json:"-"` Message string `json:"message"` Details any `json:"details,omitempty"`}You can construct one directly for custom status codes:
return kori.NewError(http.StatusPaymentRequired, "payment required")return kori.NewError(http.StatusServiceUnavailable, "service unavailable", map[string]string{ "reason": "database unreachable",})