problem

A comprehensive, idiomatic, and robust Go library for implementing RFC 7807 (Problem Details for HTTP APIs).

This library provides a standard way to return machine-readable errors from your HTTP APIs, ensuring consistency across your microservices and APIs.

Features

• Standard RFC 7807 Compliance: Supports all standard fields (type, title, status, detail, instance).
• Custom Extensions: Easily add custom arbitrary fields (extension members) that automatically flatten into the JSON root.
• Go 1.13+ Error Wrapping: Implements Error() and Unwrap() making it fully compatible with errors.Is and errors.As.
• Pre-defined HTTP Templates: Built-in templates for all common HTTP 4xx and 5xx errors.
• Fluent Options API: Clean, chainable API for building problem details.
• Zero Dependencies: Relies solely on the Go standard library.

Installation

go get github.com/semmidev/problem

Basic Usage

The easiest way to use the library is with the pre-defined templates in your HTTP handlers.

package main
import (
"net/http""github.com/semmidev/problem"
)
funcmyHandler(w http.ResponseWriter, r*http.Request) {
// Create a problem detailp:=problem.New(
problem.NotFound,
problem.WithDetail("The requested user with id 12345 was not found."),
problem.WithInstance(r.URL.Path),
)
// Write directly to the HTTP responsep.Write(w)
}

This automatically sets the Content-Type: application/problem+json header and writes:

{
"type": "about:blank",
"title": "Not Found",
"status": 404,
"detail": "The requested user with id 12345 was not found.",
"instance": "/users/12345"
}

Adding Custom Extensions

RFC 7807 allows you to add custom fields to provide domain-specific context.

p:=problem.New(
problem.UnprocessableEntity,
problem.WithDetail("You do not have enough credit."),
problem.WithExtension("balance", 30),
problem.WithExtensions(map[string]any{
"currency": "USD",
"account": "/account/12345",
}),
)

Generates:

{
"type": "about:blank",
"title": "Unprocessable Entity",
"status": 422,
"detail": "You do not have enough credit.",
"balance": 30,
"currency": "USD",
"account": "/account/12345"
}

Creating Custom Problem Types

You are encouraged to define your own problem types for domain-specific errors.

varOutOfCredit= problem.TypeTemplate{
Type: "https://example.com/probs/out-of-credit",
Title: "You do not have enough credit.",
Status: http.StatusForbidden,
}
// Later in a handler:p:=problem.New(OutOfCredit, problem.WithDetail("Current balance is 30, but that costs 50."))

Error Wrapping & Unwrapping

Because *problem.Problem implements the error interface, it can be seamlessly passed through your service layer and wrapped.

// In your repository/service layerfuncqueryDB() error {
err:= db.Query(...) // let's imagine this fails// Wrap the internal error inside a Problemreturnproblem.Wrap(err, problem.InternalServerError,
problem.WithDetail("Database timeout"),
problem.WithExtension("trace_id", "req-789"),
)
}
// In your HTTP handlerfunchandler(w http.ResponseWriter, r*http.Request) {
err:=queryDB()
iferr!=nil {
// Use errors.As or the provided IsProblem helper to extract itifp, ok:=problem.IsProblem(err); ok {
p.Write(w)
return
}
// Fallback for unknown errorsproblem.New(problem.InternalServerError).Write(w)
}
}

Example Application

Check out the example/kanban directory for a complete, runnable example of using the problem library. It features:

• Clean Architecture: Clear separation of domain rules, repositories, and HTTP handlers.
• Clear Error Boundaries: Mapping standard domain errors to RFC 7807 problem details.
• Go Chi & Govalidator: Demonstrates using the library with widely used community packages, mapping validation errors to 422 Unprocessable Entity problem extensions.