Skip to content

Validation and errors

Two kinds of validation

Kind Where Example Tool
Structural — is the input well-formed? the request DTO “price must be ≥ 0”, “email is an e-mail” validate:"…" tags + h.Bind
Business — is it allowed? the service “this SKU is already used”, “the branch belongs to another tenant” apperr.Validation(...)

Structural: struct tags

type InsertUpdateRequest struct {
Name string `json:"name" validate:"required,min=2,max=255"`
Email string `json:"email" validate:"required,email,max=255"`
Password *string `json:"password" validate:"omitempty,min=6,max=72"`
BranchID *int64 `json:"branch_id" validate:"omitempty,gt=0"`
Roles []int64 `json:"roles" validate:"omitempty,dive,gt=0"`
}

h.Bind decodes strict JSON (unknown fields are rejected when HTTP_STRICT_JSON_FIELDS=true) and runs the tags with go-playground/validator. Messages are humanised and translated (Accept-Language: en | bn).

required on numbers means “not zero”

For int fields use gte=0 (or a pointer plus required when “missing” and “zero” must differ).

Business: from the service

if exists {
return nil, apperr.Validation(map[string][]string{
"email": {"The email has already been taken."},
})
}

Field keys use dot paths for nested input (items.0.quantity).

Errors are values, responses are uniform

Services and repositories return *apperr.Error values (internal/apperr); handlers pass any error to h.Error, which renders the right problem. Never write a JSON error by hand.

return nil, apperr.New(apperr.BusinessLogicError, "This package does not offer a trial period.")
return nil, apperr.Newf(apperr.ResourceNotFound, "Product with ID '%d' was not found.", id)
return apperr.Wrap(apperr.InternalServerError, "encode overrides", err) // keeps the cause for logs

Repositories translate driver errors with database.MapError("module.op", err):

Postgres Becomes HTTP
pgx.ErrNoRows ResourceNotFound 404
23505 unique violation ResourceAlreadyExists 409
23503 foreign key violation Conflict 409
23502 not null violation ValidationFailed 422

The problem format

Every error — validation, permission, not found, rate limit, a panic — is application/problem+json (RFC 9457):

{
"type": "https://api.example.com/errors/usage-limit-exceeded",
"status": 402,
"detail": "The plan limit for this feature has been reached.",
"instance": "/api/v1/user",
"error_code": "USAGE_LIMIT_EXCEEDED",
"timestamp": "2026-11-20T10:15:04Z",
"meta": { "feature_key": "users.max", "limit": 5, "current": 5 }
}
Member When
type always — APP_URL/errors/<code>
error_code always — a stable machine-readable code clients switch on
errors 422 — {"field": ["message", …]}
meta when there is structured context (plan limits)
retry_after 429 — seconds until the next attempt
trace_id 5xx — quote it when reporting a bug; it is in the logs
debug outside production when APP_DEBUG=true

Common codes: VALIDATION_FAILED (422), UNAUTHORIZED (401), FORBIDDEN (403), RESOURCE_NOT_FOUND (404), RESOURCE_ALREADY_EXISTS / CONFLICT (409), INSUFFICIENT_PERMISSIONS, SUBSCRIPTION_REQUIRED / USAGE_LIMIT_EXCEEDED (402), RATE_LIMIT_EXCEEDED (429), TENANT_CONTEXT_NOT_RESOLVED, INTERNAL_SERVER_ERROR (500). The full list is in internal/apperr.