go-service-errors

Go Service — Errors, History, and Side Effects

Thesis: Constraint violations and scan mistakes are expected failure modes — translate them to apperror, never swallow them as 500s or silent drops.

Refrain: Check → Translate → Log

Reference files: auth/auth.go, feature/feature.go

Error Handling

• Always check pgx.ErrNoRows explicitly — return apperror.NotFound for missing entities.
• Check real DB errors before ErrNoRows: if err != nil && err != pgx.ErrNoRows { return 500 }.
• Never _ = pool.Exec(...) — log failures with logger.Error.
• Pass bare resource nouns to apperror.NotFound("User") — not "User not found" (double-suffix).

PostgreSQL Error Translation Checklist

When a service method writes to a table with a UNIQUE, CHECK, or FOREIGN KEY constraint, the corresponding pgconn.PgError SQLSTATE must be translated to an apperror. A bare 500 from a PG constraint violation is always a bug — the constraint exists because the situation is expected.

SQLSTATE	Meaning	Translate to
23505	unique_violation	apperror.Conflict("...")
23503	foreign_key_violation	apperror.BadRequest (parent missing) or apperror.Conflict (child blocking delete)
23514	check_violation	apperror.BadRequest with the constraint name
23502	not_null_violation	apperror.BadRequest (input was missing) or apperror.Internal (code bug)

Standard pattern (always use errors.As, never type assertion — the error may be wrapped):

var pgErr *pgconn.PgError
if errors.As(err, &pgErr) && pgErr.Code == "23505" {
    return apperror.Conflict("...")
}
return apperror.Internal(fmt.Errorf("...: %w", err))

When the same translation appears in two or more methods, extract a helper like translateUniqueConflict(err, resource) and unit-test it directly with synthetic *pgconn.PgError values. The TOCTOU race that triggers 23505 isn't deterministic from an integration test, but a unit test of the helper pins the contract.