Documentation
¶
Index ¶
- Constants
- func Error(w http.ResponseWriter, r *http.Request, status int, code, message string)
- func ErrorWith(w http.ResponseWriter, r *http.Request, status int, code, message string, ...)
- func JSON(w http.ResponseWriter, status int, data any)
- func JSONFail(w http.ResponseWriter, status int, message string, data any)
- func JSONList(w http.ResponseWriter, status int, items any, total, limit, offset int)
- func JSONListWithMeta(w http.ResponseWriter, status int, items any, meta any)
- func JSONWithMessage(w http.ResponseWriter, status int, message string, data any)
- func ValidationError(w http.ResponseWriter, r *http.Request, fields map[string]string)
- type ErrorOption
- type ErrorResponse
- type ListMeta
- type ListResponse
- type SuccessResponse
- type ValidationErrorResponse
Constants ¶
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" CodeForbidden = "FORBIDDEN" CodeRateLimited = "RATE_LIMITED" CodeAuthzError = "AUTHZ_ERROR" )
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 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 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 ¶
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.