Errors¶

Brama speaks two error vocabularies to two audiences, and the split is deliberate. What a client reads is the HTTP error body — a stable type and code that predate the fleet vocabulary and do not change. What an operator reads is the wisent-errors envelope, logged beside the client body with the fleet's code, failure point, and impact. Where the two readings differ, both are on the line; neither stands in for the other.

The client contract¶

Every public error uses this body:

{
  "error": {
    "message": "bounded human-readable detail",
    "type": "stable_class",
    "code": "stable_code",
    "retryable": false,
    "attempts": <provider calls the dispatch counted>
  }
}

retryable is stated explicitly, and attempts bounds any replay the caller considers: selector and credential replay never exceeds it. A refusal made by a dispatch states the provider calls it counted, zero included; a refusal Brama made before any dispatch (authentication, transport, a malformed request, an alias it cannot serve) asked no provider and carries no attempts key. Message text is diagnostic, not the machine contract.

Subscription reports also carry ok and errors. These are completed reports, so HTTP 200 can contain ok: false and partial rows. The errors array contains standard Wisent envelopes with failure_point, error_code, detail, and context identifying the account and attempt time. Discovery failures are not empty inventories; expired measurements are not current; missing metrics are not zero. CLI reports exit non-zero and desktop clients show the same errors beside retained stale readings.

A pool can contain both a refused credential and an account that is only out of quota. When no account serves the request, an observed quota refusal takes precedence: Brama returns that provider's original 429 message rather than claiming every account needs a new sign-in. A recorded quota block returns 429 subscription_unavailable without contacting that provider again. When no account can recover by waiting for a quota, the authorization refusal is 503 subscription_reauthorization_required with retryable: true: it wakes the gateway's own maintenance, which renews the grant or signs the member in through Weles. Buffered and streaming requests use the same precedence.

The code a refusal is answered with comes from the class the refusal was stated with where it was built — the provider's HTTP status for a provider refusal, Brama's own reason for a refusal Brama makes — and never from the words of its message. A message may change its wording; its code does not. A walk over several candidates is answered with the most telling class it met: a spent balance, then a rate window or a quota block a wait reaches, then an authorization failure, and otherwise 429 subscription_unavailable.

A selector request (best, any, task:<name>) whose every listed member the ledger already refuses is refused before any vault child or provider is asked, with the message every subscription is refused by the ledger before any is read: <member>: <reason>; … and attempts: 0. The reason per member is the ledger's own: awaiting sign-in: <the provider's refusal> for a grant the provider disowned or an operator retired (503 subscription_reauthorization_required), paid balance spent, recorded until <UTC instant>: <the provider's refusal> (502 provider_quota_exhausted, not retryable) and rate limited, the block lifts at <UTC instant>: <the provider's refusal> (429 provider_rate_limited, retryable); the class answered is the most telling one among the members, in the walk's own precedence. A member the ledger does not refuse is read and discovered; when that read fails the message begins could not discover native provider models: instead. When a member awaiting sign-in has an automatic sign-in attempt that failed and still stands, either message ends with ; the automatic sign-in that renews them failed: <member>: <code>: <detail>; …, the failure code and detail that attempt recorded (for a Weles refusal, the stage and Weles's own words), so the cause of a pool nobody can renew is in the refusal itself. A pool every member of which needs a sign-in is refused with no model: every member of the subscription pool needs a new sign-in, so no request was sent:, and each member there reads the automatic Weles sign-in that renews it failed: <code>: <detail> in place of renewed by the automatic Weles sign-in while such a failure stands.

A refusal that says every credential was rejected by the provider ends with automatic sign-in: <member>: <state>; …, one state per recorded member of the provider: retired, never ran, last <result> at <UTC instant>, or failed (<code>: <detail> (attempted at <UTC instant>)) while that failure still stands. A failure stops standing once the member's credential is renewed after the attempt, including an attempt refused before any run started. A member inside a recorded block carries , held until <UTC instant> by the provider's answer: <the provider's refusal>, so a member that only waits for its spent window is not read as one that needs a sign-in.

The operator envelope¶

src/core/failure.rs is the one place Brama's own vocabulary becomes the fleet's, using the wisent-errors crate for everything derivable and deciding nothing itself. Every envelope carries service brama, one failure point, an impact, and the reason the layer below gave, verbatim — the field shape and a captured example are in concepts/envelope and concepts/failure-point:

Derivation is centralised: severity, retryability, and outage always come from the crate, never from a call site. Where an upstream HTTP status exists, the fleet code is classified from that status by the crate's catalogue; otherwise Brama's own kind is translated exactly once:

Every arm preserves what the client contract already said about retrying: retryable kinds map to retryable codes and permanent ones do not. Ordinary HTTP admission errors retain their existing body. Subscription reports expose their Wisent envelopes in errors so partial failures are visible without reading server logs; the same reasons remain in the usage ledger.

Where errors are not allowed¶

Logs and error bodies never include bearer values, HMAC signatures, capability IDs, raw credentials, request bodies, prompt text, raw provider payloads, or donated secrets. /readyz reports a refusal in the words of whatever refused it — provider name and verdict only, no secret in the body (http-api). The full state and recovery contract behind each code is CORE.md.