apierror`

Status: Accepted
Date: 2026-06-10
Authors: IBEX Harness team

Context

M1.4.2 requires typed environment loading and a canonical error code registry before Phase 2 adds Python services and LLM provider forwarding. Prior milestones deferred both concerns:

ADR-0015: proxy rate-limit config in services/proxy/internal/config until M1.4.2
ADR-0013: stable HTTP error envelope in services/proxy/internal/errors until M1.4.2

Both services/auth and services/proxy used scattered os.Getenv calls with per-field validation.

Decision

1) `packages/config`

All Go service environment loading uses config.Load[T]() / config.MustLoad[T]() with struct env:"VAR" tags
Underlying parser: github.com/caarlos0/env/v11
config.Secret and secret:"true" tags redact values in config.LogDebug
Service-specific validation (ports, DSN format, rate-limit overrides) remains in services/*/internal/config after env parse
packages/telemetry keeps internal ConfigFromEnv for OTEL_* variables; services compose telemetry config after IBEX env load

2) `packages/apierror`

Single registry for HTTP JSON error codes and gRPC status mappings
Error code strings are stable per ADR-0013 — this ADR relocates the registry; it does not rename shipped codes (MISSING_TOKEN, not UNAUTHENTICATED)
Full envelope preserved: field_errors, detail, docs_url, timestamp (ADR-0013)
Handlers use apierror.Write / apierror.WriteStatus; no raw error code string literals outside this package

3) Boundaries

Package	May import	Must not
`packages/config`	stdlib, `caarlos0/env`	service packages, `packages/logger` (bootstrap ordering)
`packages/apierror`	stdlib, `google.golang.org/grpc/codes`	service handlers, DB, Redis

Consequences

New error codes are added only in packages/apierror
New required env vars are documented via struct tags + .env.example + ENVIRONMENT_VARIABLES.md
Phase 2 Python services document pydantic-settings pattern separately (AGENTS.md)

References

M1.4.2 milestone
ADR-0013
AGENTS.md
ARCHITECTURE_LAYERING.md — consumer-owned ports vs intentional shared package interfaces (session / idempotency / directive)

Was this page helpful?

Context

M1.4.2 requires typed environment loading and a canonical error code registry before Phase 2 adds Python services and LLM provider forwarding. Prior milestones deferred both concerns:

ADR-0015: proxy rate-limit config in services/proxy/internal/config until M1.4.2

ADR-0013: stable HTTP error envelope in services/proxy/internal/errors until M1.4.2

Both services/auth and services/proxy used scattered os.Getenv calls with per-field validation.

Decision

All Go service environment loading uses config.Load[T]() / config.MustLoad[T]() with struct env:"VAR" tags

Underlying parser: github.com/caarlos0/env/v11

config.Secret and secret:"true" tags redact values in config.LogDebug

Service-specific validation (ports, DSN format, rate-limit overrides) remains in services/*/internal/config after env parse

packages/telemetry keeps internal ConfigFromEnv for OTEL_* variables; services compose telemetry config after IBEX env load

Single registry for HTTP JSON error codes and gRPC status mappings

Error code strings are stable per ADR-0013 — this ADR relocates the registry; it does not rename shipped codes (MISSING_TOKEN, not UNAUTHENTICATED)

Full envelope preserved: field_errors, detail, docs_url, timestamp (ADR-0013)

Handlers use apierror.Write / apierror.WriteStatus; no raw error code string literals outside this package

Package	May import	Must not
`packages/config`	stdlib, `caarlos0/env`	service packages, `packages/logger` (bootstrap ordering)
`packages/apierror`	stdlib, `google.golang.org/grpc/codes`	service handlers, DB, Redis