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 logsRepositories 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.

