respond

Documentation

Index

• func BadRequest(w http.ResponseWriter, r *http.Request, message string)
• func Conflict(w http.ResponseWriter, r *http.Request, message string)
• func ConflictCoded(w http.ResponseWriter, r *http.Request, field, code, message string)
• func ConflictField(w http.ResponseWriter, r *http.Request, field, message string)
• func Error(w http.ResponseWriter, r *http.Request, status int, ...)
• func Forbidden(w http.ResponseWriter, r *http.Request, message string)
• func FromError(w http.ResponseWriter, r *http.Request, err error, resource string)
• func InternalError(w http.ResponseWriter, r *http.Request)
• func JSON(w http.ResponseWriter, r *http.Request, status int, data any)
• func List(w http.ResponseWriter, r *http.Request, data any, total int)
• func NotFound(w http.ResponseWriter, r *http.Request, resource string)
• func NotFoundCoded(w http.ResponseWriter, r *http.Request, code, message string)
• func PreconditionFailed(w http.ResponseWriter, r *http.Request, message string)
• func RateLimited(w http.ResponseWriter, r *http.Request)
• func Unauthorized(w http.ResponseWriter, r *http.Request, message string)
• func Validation(w http.ResponseWriter, r *http.Request, message string)
• func ValidationCoded(w http.ResponseWriter, r *http.Request, field, code, message string)
• func ValidationField(w http.ResponseWriter, r *http.Request, field, message string)
• type ErrorBody
• type ErrorDetail
• type SafeMessageError

Functions

func BadRequest

func BadRequest(w http.ResponseWriter, r *http.Request, message string)

func Conflict

func Conflict(w http.ResponseWriter, r *http.Request, message string)

func ConflictCoded

func ConflictCoded(w http.ResponseWriter, r *http.Request, field, code, message string)

ConflictCoded is the 409 analogue of ValidationCoded — same code+field plumbing, different status. Default code is "already_exists".

func ConflictField

func ConflictField(w http.ResponseWriter, r *http.Request, field, message string)

ConflictField writes a 409 response with the offending field name in the envelope's Param slot so the frontend can attach the message to the right input. Use when a create/update fails because a user-supplied value collides with an existing record (plan.code, coupon.code, etc.).

func Error

func Error(w http.ResponseWriter, r *http.Request, status int, errType, code, message string)

Error writes a Stripe-style error response. Format: {"error": {"type": "...", "message": "...", "code": "...", "param": "..."}}

func Forbidden

func Forbidden(w http.ResponseWriter, r *http.Request, message string)

func FromError

func FromError(w http.ResponseWriter, r *http.Request, err error, resource string)

FromError translates a service/store error into the appropriate HTTP response. This is the single place where domain errors become API responses.

Usage in handlers:

customer, err := h.svc.Create(ctx, tenantID, input)
if err != nil {
    respond.FromError(w, r, err, "customer")
    return
}

func InternalError

func InternalError(w http.ResponseWriter, r *http.Request)

func JSON

func JSON(w http.ResponseWriter, r *http.Request, status int, data any)

JSON writes a success response with standard headers.

func List

func List(w http.ResponseWriter, r *http.Request, data any, total int)

List writes a paginated list response.

func NotFound

func NotFound(w http.ResponseWriter, r *http.Request, resource string)

func NotFoundCoded

func NotFoundCoded(w http.ResponseWriter, r *http.Request, code, message string)

NotFoundCoded is the 404 analogue — message is built by the caller since domain-specific 404s often have more context than "<resource> not found".

func PreconditionFailed

func PreconditionFailed(w http.ResponseWriter, r *http.Request, message string)

PreconditionFailed writes a 412 response. The canonical use is optimistic concurrency: the caller sent If-Match with the ETag they last saw and a concurrent writer has since bumped the version. The client should GET the resource, re-apply its edits against the fresh copy, and retry.

func RateLimited

func RateLimited(w http.ResponseWriter, r *http.Request)

func Unauthorized

func Unauthorized(w http.ResponseWriter, r *http.Request, message string)

func Validation

func Validation(w http.ResponseWriter, r *http.Request, message string)

func ValidationCoded

func ValidationCoded(w http.ResponseWriter, r *http.Request, field, code, message string)

ValidationCoded writes a 422 response with a domain-specific error code in the envelope's Code slot, the offending field (optional) in Param, and the message. Use when the caller has a stable code (e.g. "coupon_expired") that API integrators will switch on.

An empty code falls back to "validation_error" so the envelope is never missing a code.

func ValidationField

func ValidationField(w http.ResponseWriter, r *http.Request, field, message string)

ValidationField writes a 422 response with the offending field name in the envelope's Param slot. Use for inline handler validation where the field is known at the call site (service-layer validation is routed via FromError, which pulls the field off DomainError automatically).

Types

type ErrorBody

type ErrorBody struct {
	Error ErrorDetail `json:"error"`
}

type ErrorDetail

type ErrorDetail struct {
	Type      string `json:"type"`
	Code      string `json:"code"`
	Message   string `json:"message"`
	RequestID string `json:"request_id"`
	Param     string `json:"param,omitempty"`
}

type SafeMessageError

type SafeMessageError = errs.SafeMessageError

SafeMessageError is an alias for errs.SafeMessageError — the opt-in marker for error types that own their own operator-safe rendering. The interface lives in internal/errs so non-HTTP contexts (catchup orchestrator, scheduler error rollups) can use the same dispatch shape; this alias preserves existing call sites like `respond.FromError(... &MyErr{})` without forcing a churn.

ADR-026.