response

package
v0.23.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 3, 2026 License: MIT Imports: 4 Imported by: 0

Documentation

Index

Constants

View Source
const (
	CodeNotFound      = "NOT_FOUND"
	CodeInternalError = "INTERNAL_ERROR"
	CodeInvalidJSON   = "INVALID_JSON"
	CodeUnknownField  = "UNKNOWN_FIELD"
	CodeBodyTooLarge  = "BODY_TOO_LARGE"
	// CodeUnsupportedMediaType is used with HTTP 415 when the request body's
	// Content-Type is not a JSON media type (application/json or
	// application/*+json), or is missing where a body is required.
	CodeUnsupportedMediaType = "UNSUPPORTED_MEDIA_TYPE"
	// CodeUnprocessableEntity is used with HTTP 422 when the request is well
	// formed but violates a business rule.
	CodeUnprocessableEntity = "UNPROCESSABLE_ENTITY"
	// CodeExportTooLarge is used with HTTP 413 when a requested export exceeds
	// the server's row cap. Distinct from CodeBodyTooLarge, which is about the
	// request body.
	CodeExportTooLarge     = "EXPORT_TOO_LARGE"
	CodeValidationError    = "VALIDATION_ERROR"
	CodeConflict           = "CONFLICT"
	CodeUnauthorized       = "UNAUTHORIZED"
	CodeForbidden          = "FORBIDDEN"
	CodeRateLimited        = "RATE_LIMITED"
	CodeAuthzError         = "AUTHZ_ERROR"
	CodeServiceUnavailable = "SERVICE_UNAVAILABLE"
)

Error envelope contract. Every error response carries three layers:

  • code: a generic, stable category (NOT_FOUND, CONFLICT, ...). Modules do NOT define their own codes; use the constants below.
  • error: an optional stable identifier for one specific domain error (SCREAMING_SNAKE_CASE, e.g. CORREO_EN_USO), chosen by the consumer module and attached with WithErrorID. Set it on every business error.
  • message: human-readable text that may change at any time.

Clients must branch on error (falling back to code), never on message. When the error belongs to a single input field, WithField names it.

Standard error codes for API responses.

Variables

This section is empty.

Functions

func Error

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

Error writes the standard error envelope. It is ErrorWith without options.

func ErrorWith added in v0.8.0

func ErrorWith(w http.ResponseWriter, r *http.Request, status int, code, message string, opts ...ErrorOption)

ErrorWith writes the standard error envelope, applying opts to add a stable error identifier and/or the offending field.

func JSON

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

func JSONFail

func JSONFail(w http.ResponseWriter, status int, message string, data any)

func JSONList

func JSONList(w http.ResponseWriter, status int, items any, total, limit, offset int)

JSONList writes a paginated list response.

func JSONListWithMeta

func JSONListWithMeta(w http.ResponseWriter, status int, items any, meta any)

JSONListWithMeta writes a paginated list response with a custom meta object.

func JSONWithMessage

func JSONWithMessage(w http.ResponseWriter, status int, message string, data any)

func ValidationError

func ValidationError(w http.ResponseWriter, r *http.Request, fields map[string]string)

ValidationError sends a 400 response containing per-field validation errors.

Types

type ErrorOption added in v0.8.0

type ErrorOption func(*ErrorResponse)

ErrorOption customizes an ErrorResponse built by ErrorWith.

func WithErrorID added in v0.8.0

func WithErrorID(id string) ErrorOption

WithErrorID sets the stable per-domain-error identifier (the "error" key), in SCREAMING_SNAKE_CASE, e.g. "CORREO_EN_USO".

func WithField added in v0.8.0

func WithField(name string) ErrorOption

WithField sets the offending input field name (the "field" key).

type ErrorResponse

type ErrorResponse struct {
	Success bool   `json:"success"`
	Message string `json:"message"`
	Code    string `json:"code"`
	// Error is the stable per-domain-error identifier (e.g. CORREO_EN_USO).
	// Omitted when not set.
	Error string `json:"error,omitempty"`
	// Field names the offending input field, when the error belongs to one.
	// Omitted when not set.
	Field string `json:"field,omitempty"`
	// RequestID is the request's ID (the X-Request-Id response header), for
	// matching an error report with its log lines. Omitted without
	// httpx/middleware.RequestID.
	RequestID string `json:"request_id,omitempty"`

} //	@name	ErrorResponse

ErrorResponse is the standard error envelope for API responses.

type ListMeta

type ListMeta struct {
	Total  int `json:"total"`
	Limit  int `json:"limit"`
	Offset int `json:"offset"`

} //	@name	ListMeta

ListMeta contains pagination metadata for list responses.

type ListResponse

type ListResponse struct {
	Success bool     `json:"success"`
	Message string   `json:"message"`
	Data    any      `json:"data"`
	Meta    ListMeta `json:"meta"`

} //	@name	ListResponse

ListResponse is the envelope for paginated list endpoints.

type SuccessResponse

type SuccessResponse struct {
	Success bool   `json:"success"`
	Message string `json:"message"`
	Data    any    `json:"data"`

} //	@name	SuccessResponse

SuccessResponse is the standard success envelope for API responses.

type ValidationErrorResponse

type ValidationErrorResponse struct {
	Success bool              `json:"success"`
	Message string            `json:"message"`
	Code    string            `json:"code"`
	Fields  map[string]string `json:"fields"`
	// RequestID is the request's ID, as in ErrorResponse.
	RequestID string `json:"request_id,omitempty"`

} //	@name	ValidationErrorResponse

ValidationErrorResponse is a 400 response with per-field errors.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL