feat: add WithPlatformCode for domain-level error identity (v0.10.0) #2

claude · 2026-03-25T16:33:55-06:00

claude commented

2026-03-25 16:33:55 -06:00

Summary

Adds WithPlatformCode / PlatformCode() to *Err — an optional domain-level error identifier that is fully decoupled from the transport-level Code.

Why two codes?

Field	Layer	Purpose
`Code`	Transport	Maps to HTTP status / gRPC status. Stable, bounded (`NOT_FOUND` → 404).
`PlatformCode`	Domain/Platform	Identifies the specific domain error (`EMPLOYEE_NOT_FOUND`). Open-ended, consumer-defined.

A NOT_FOUND transport code cannot tell a frontend whether an employee, a role, or a branch was missing — it falls back to a generic message. PlatformCode gives the frontend the exact signal it needs to render a specific translated message, without the backend carrying any locale-specific copy.

Platform codes are optional. Errors without a user-actionable meaning (500 internals, infrastructure failures, auth rejections) carry none.

Changes

(*Err).WithPlatformCode(code string) *Err — chainable builder
(*Err).PlatformCode() string — getter (empty string if not set)
MarshalJSON includes "platformCode" when set, omits otherwise (omitempty)
6 new tests covering: set+get, empty default, chaining, JSON include/omit

Backwards compatibility

Fully additive — no existing signatures, behaviour, or JSON output changed for errors that don't use WithPlatformCode.

Test plan

go test ./... passes
platformCode present in JSON when set
platformCode absent from JSON when not set
Chaining with WithContext and WithError works correctly
Code() unaffected by WithPlatformCode

🤖 Generated with Claude Code

## Summary Adds `WithPlatformCode` / `PlatformCode()` to `*Err` — an optional domain-level error identifier that is fully decoupled from the transport-level `Code`. **Why two codes?** | Field | Layer | Purpose | |-------|-------|---------| | `Code` | Transport | Maps to HTTP status / gRPC status. Stable, bounded (`NOT_FOUND` → 404). | | `PlatformCode` | Domain/Platform | Identifies the specific domain error (`EMPLOYEE_NOT_FOUND`). Open-ended, consumer-defined. | A `NOT_FOUND` transport code cannot tell a frontend whether an employee, a role, or a branch was missing — it falls back to a generic message. `PlatformCode` gives the frontend the exact signal it needs to render a specific translated message, without the backend carrying any locale-specific copy. **Platform codes are optional.** Errors without a user-actionable meaning (500 internals, infrastructure failures, auth rejections) carry none. ## Changes - `(*Err).WithPlatformCode(code string) *Err` — chainable builder - `(*Err).PlatformCode() string` — getter (empty string if not set) - `MarshalJSON` includes `"platformCode"` when set, omits otherwise (`omitempty`) - 6 new tests covering: set+get, empty default, chaining, JSON include/omit ## Backwards compatibility Fully additive — no existing signatures, behaviour, or JSON output changed for errors that don't use `WithPlatformCode`. ## Test plan - [x] `go test ./...` passes - [x] `platformCode` present in JSON when set - [x] `platformCode` absent from JSON when not set - [x] Chaining with `WithContext` and `WithError` works correctly - [x] `Code()` unaffected by `WithPlatformCode` 🤖 Generated with [Claude Code](https://claude.com/claude-code)

claude added 1 commit 2026-03-25 16:33:56 -06:00

feat: add WithPlatformCode for domain-level error identity 5e92f17f3b

Adds an optional PlatformCode field to *Err, decoupled from the
transport-level Code. Code drives HTTP/gRPC status mapping;
PlatformCode is a stable domain identifier for consuming applications
(e.g. a frontend performing i18n) to map errors to localised messages.

Platform codes are optional — errors without a user-actionable meaning
(500s, infrastructure failures, auth rejections) carry none.

Fully backwards-compatible: no existing signatures or JSON output changed
for errors without a platform code.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Rene Nochebuena approved these changes 2026-03-25 16:42:07 -06:00

Rene Nochebuena left a comment

LGTM

Rene Nochebuena merged commit 5381bccbf7 into main

2026-03-25 16:42:15 -06:00

Rene Nochebuena deleted branch feature/platform-code

2026-03-25 16:42:15 -06:00

Rene Nochebuena referenced this issue from a commit

2026-03-25 16:42:17 -06:00

feat: add WithPlatformCode for domain-level error identity (v0.10.0) (#2)

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: go/xerrors#2