Errors are part of the contract

Principles

The error model

Both backends use the same ten kinds, and the kind alone decides the status. A failure also carries a module-qualified code, a public message, optional field problems, and, privately, details and a cause.

// backend/go/internal/identity/app/errors.go
ErrSignInDenied = apperrors.New(apperrors.Unauthenticated, "sign in was refused").
    WithType("identity.sign_in_denied").
    WithPublicMessage("Email or password is incorrect.")

// backend/nest/src/shared/errors
type Result<T, E> =
  | { readonly ok: true; readonly value: T }
  | { readonly ok: false; readonly error: E };

type Failure = Readonly<{
  kind: Kind; message: string; type?: string;
  fields?: Readonly<Record<string, string>>;
}>;

In Go, an error is an ordinary error built with New or Wrap and refined with immutable With* methods, so errors.Is still matches the original sentinel. context.Canceled and DeadlineExceeded become canceled andtimeout. In Nest, expected failures are Result values whose message is the public one; details and causes live in a private map, and a controller throws AppError only to reach the problem filter.

The response

Every failure is application/problem+json with the same fields in both backends. The OpenAPI schema forbids any others.

HTTP/1.1 401 Unauthorized
Content-Type: application/problem+json; charset=utf-8
X-Request-ID: 0192c7d8-…

{
  "type": "urn:bento:problem:unauthenticated",
  "title": "Unauthorized",
  "detail": "Email or password is incorrect.",
  "kind": "unauthenticated",
  "status": 401,
  "code": "identity.sign_in_denied",
  "request_id": "0192c7d8-…"
}

Each failure response in the OpenAPI spec lists the codes it can carry in x-bento-codes, 247 lists in all. That is the catalogue frontends write their messages against.

'400':
  x-bento-codes:
    - http.invalid_json
    - identity.invalid_email
    - identity.invalid_password

Where failures come from

Safe by default

Limits, sessions and step-up

Some failures ask the client to do something specific. They have their own codes:

Across services

A capability call can fail in three ways, and the caller can always tell them apart:

There are no retries. The calling module turns a transport failure into its own dependency failure, and only a successful negative answer may deny:

// backend/go/internal/usage/app/errors.go
func AuthorizationCheckFailed(cause error) error {
    return apperrors.New(dependencyKind(cause), "unable to check account access").
        WithType("usage.authorization_check_failed").
        WithPublicMessage("Account usage is temporarily unavailable.").
        WithCause(cause)
}

So a permission check that fails is 503 usage.authorization_check_failed, while a permission check that answers "no" is 404 usage.account_not_found. A few callers degrade instead: whenidentity.profiles.v1 fails, names come back empty rather than failing the page.backend/ARCHITECTURE-ENFORCEMENT.md lists what a failure means for every capability.

Behind the edge, any invalid, expired or unsigned assertion is 401 principal.assertion_invalid, with no hint about which check failed. A bad service token at a capability is401 capability.unauthenticated, and a caller the capability does not accept is403 capability.caller_not_allowed.

Events, jobs and caches

1. Publish failsThe outbox row stays unpublished and is retried 5 seconds later, without holding up the rest of the batch. Writes keep succeeding while the transport is down.
2. Consumer failsunavailable, timeout and rate_limited are retried. Any other kind, or an unrecognised failure (events.consumer_defect), is permanent.
3. DeadA permanent failure, or the tenth attempt, marks the delivery dead. It is acknowledged so it cannot block other consumers.
4. PoisonAn outbox row that cannot be decoded is quarantined with its original bytes and a reason, and never published.
5. Repairevents.sh dead, quarantined, requeue and replay. Consumers that already finished an event skip it, and published rows are kept for 7 days to replay from.

Realtime

On the WebSocket, a refused operation is an error message with a code, such astopic_denied or subscription_limit, and the connection stays open. If the permission check behind a subscription fails, the topic is not added: it fails closed. Closing is reserved for these cases, each announced with a closing message first:

In the frontends

Next.js and SvelteKit share the same kernel, and the mobile app has its own copy: a Resulttype and a Failure union over the same ten kinds.

1. ProxyIf the backend cannot be reached, the same-origin proxy answers 502 http.upstream_unavailable in the same problem shape.
2. FetchA network error becomes unavailable, an abort canceled, an unreadable success http.invalid_response. Requests time out after 15 seconds.
3. DecodedecodeFailure reads the problem. A missing body or unknown kind falls back to the HTTP status; Retry-After becomes milliseconds.
4. QueryA session_required anywhere clears the cache and sends the user to sign in, once. Queries do not retry.
5. Presentpresent() tries the screen's message for the code, then common codes, then a message for the kind, so an unknown code still reads sensibly. A 503 always reads as "not responding", never "not allowed".
6. RecoverwithStepUp prompts and retries once on a re-authentication code; forms show fields next to each input; the terms dialog cannot be dismissed while acceptance is required.

The rules for screens are in frontend/UI-INTEGRATION.md ("Errors"): branch on the code, never parse detail, show request_id in the default branch, and never retry a 429 automatically.

Observing failures

A failed span has status Error and error.type set to the code, never the message, so traces group by cause without leaking data.

Known gaps

• Nothing checks x-bento-codes against the codes the backends actually return.
• No test compares error codes between Go and Nest directly. The end-to-end suites assert some codes on both, which gives partial parity.
• Nest has no process-level handler for unhandled rejections or uncaught exceptions.
• contracts/edge/README.md says an unreachable upstream on a WebSocket upgrade is a 502; the code returns 503 edge.upstream_failed.
• The mobile adapter now sends idempotency keys and If-Match; the remaining error/API work is broader authenticated route coverage and a systematic cross-runtime error-code parity pass.

In the repository