Go Error

Go Error

Generate typed custom errors for module-level errs packages.

When to Use

• Add new custom typed error definitions to a module
• Extend existing errs.go with new error codes
• Create validation error helpers with field-level details

Pattern

Place errors in:

internal/modules/<module>/errs/errs.go

Each module error file follows:

1. package errs 2. Imports:

• net/http
• brickserrs "github.com/cristiano-pacheco/bricks/pkg/errs"

3. var (...) block with exported error variables 4. Error creation via:

• brickserrs.New("<MODULE>_<NN>", "<message>", http.<Status>, nil)

5. Optional helper constructors for validation errors that carry field-level details

Example Structure

package errs

import (
	"net/http"

	brickserrs "github.com/cristiano-pacheco/bricks/pkg/errs"
)

var (
	// ErrProfileValidationFailed is returned when profile validation fails.
	ErrProfileValidationFailed = brickserrs.New(
		"PROFILE_01",
		"profile validation failed",
		http.StatusBadRequest,
		nil,
	)
	// ErrProfileNotFound is returned when the profile is not found.
	ErrProfileNotFound = brickserrs.New("PROFILE_02", "profile not found", http.StatusNotFound, nil)
)

// NewProfileValidationError returns a structured validation error with field-level details.
func NewProfileValidationError(details []brickserrs.Detail) *brickserrs.Error {
	return brickserrs.New(
		ErrProfileValidationFailed.Code,
		ErrProfileValidationFailed.Message,
		ErrProfileValidationFailed.Status,
		details,
	)
}

Generation Steps

1. Identify error details:

• Target module (e.g., catalog, profile, ai, export)
• Error variable name (ErrProfileNotFound)
• Lowercase message ("profile not found")
• HTTP status (http.StatusNotFound)

2. Find the next code:

• Open internal/modules/<module>/errs/errs.go
• Extract existing codes for that module prefix
• Allocate the next available sequential code:
• Single digits are zero-padded: CATALOG_01, CATALOG_02, ..., CATALOG_09
• Double digits are not padded: CATALOG_10, CATALOG_11, ...
• Keep code uniqueness inside the module

3. Add the new error:

• Insert into the module var (...) block
• Keep domain-group ordering used by the file
• Add a short doc comment when comments are already present in the file

4. Add a helper constructor if needed:

• When the error is a validation error that carries field-level details, add a NewXxxValidationError(details []brickserrs.Detail) *brickserrs.Error function
• Reuse the pre-defined variable's .Code, .Message, and .Status fields

5. Validate usage path:

• Ensure new/updated usecases, validators, handlers, or enum constructors return the new typed error
• Do not return raw errors.New(...) from business flows when a typed module error exists

6. Update translations (mandatory):

• Every new custom error must add a translation entry in locales/en.json under the "errors" key
• Use the error code as key and a properly capitalized, user-facing sentence as value: "PROFILE_02": "Profile not found"
• If additional locale files exist (for example locales/pt_BR.json), add the same key there too
• Keep translation keys and structure consistent across all locale files
• Do not merge a new custom error without the corresponding locale updates

Naming Conventions

• Variable: Err + clear domain phrase in PascalCase
• Example: ErrProfileNotFound, ErrAIGenerationFailed
• Code: <MODULE>_<NN>
• CATALOG_09, EXPORT_15, AI_07
• Always at least 2 digits; single digits are zero-padded
• Message:
• All lowercase in brickserrs.New() — the locale file (locales/en.json) provides the user-facing capitalized form
• Short and specific, no trailing punctuation
• Examples: "profile not found", "invalid prompt type", "ai provider unavailable"
• HTTP status:
• Validation errors: http.StatusBadRequest
• Auth failures: http.StatusUnauthorized / http.StatusForbidden
• Missing resources: http.StatusNotFound
• Conflicts: http.StatusConflict
• Rate limit: http.StatusTooManyRequests
• Upstream/AI failures: http.StatusBadGateway
• Capacity/availability: http.StatusServiceUnavailable
• Infra/internal failures: http.StatusInternalServerError

Implementation Checklist

• [ ] Open target internal/modules/<module>/errs/errs.go
• [ ] Compute next unique module code (zero-padded 2-digit format)
• [ ] Add exported Err... variable with brickserrs.New(...)
• [ ] Use all-lowercase message string
• [ ] Match existing domain-group ordering style
• [ ] Ensure message and status align with domain behavior
• [ ] Add NewXxxValidationError(details []brickserrs.Detail) helper if it is a validation error
• [ ] Replace raw error returns in calling code with typed errs.Err... where applicable
• [ ] Add translation for the new error in locales/en.json under "errors" with proper sentence-case value
• [ ] Add the same translation key in every other existing locale file (e.g., locales/pt_BR.json)
• [ ] Run make lint to catch style and static analysis issues
• [ ] Run make nilaway to ensure no nil pointer dereferences are introduced

Usage Pattern

if input.Phone == "" {
	return errs.ErrPhoneNumberRequired
}

if profile == nil {
	return errs.ErrProfileNotFound
}

Critical Rules

• No standalone functions: When a file contains a struct with methods, do not add standalone functions. Use private methods on the struct instead.
• Do not create a new error package; use module-local internal/modules/<module>/errs
• Do not duplicate codes within the same module
• Do not return persistence or infrastructure-specific raw errors to transport when a typed domain error exists
• Keep error messages stable once exposed, unless migration/compatibility impact is accepted
• Every new custom error requires locale entries in locales/en.json and all other existing locale files
• Messages in brickserrs.New() are always lowercase; user-facing capitalization lives in the locale file