Runbook¶

Something at the gateway looks wrong — which command do you run first, and what does its answer mean? This page is the symptom list. Find the row that matches what you are reading, then follow it to the page that quotes the exact sentence the product prints and names the repair. The error vocabulary itself is in errors.

Three pages hold the entries:

Startup and readiness — the endpoint, the process, /health, /readyz, and the transport guard.
Credentials and subscriptions — which credential was supposed to pay for the request, and what refused it.
Routes and ledger — the route registry document, PUT /v1/admin/routes, brama routes migrate, and the usage ledger.

Symptoms¶

Symptom	Entry
A call to the documentation site answers `404 api_not_published`	Startup and readiness
`brama serve` refuses to start	Startup and readiness
A download under `/download` answers an error instead of the file	Download
`/health` is `ok` but nothing works	Startup and readiness
`/readyz` answers 503	Startup and readiness
Requests from another machine answer 426	Startup and readiness
A request answers `503 credential_unauthorized`	Credentials and subscriptions
A request answers `429 subscription_unavailable`	Credentials and subscriptions
A subscription reads `burnt`	Credentials and subscriptions
`subscription refresh` reports it attempted nothing	Credentials and subscriptions
An account vanished from every listing but keeps paying	Credentials and subscriptions
A provider refuses its own credential	Credentials and subscriptions
A route update is refused	Routes and ledger
The ledger looks wrong, not the pool	Routes and ledger

How to read an entry¶

Every entry starts from the symptom, quotes the product's own sentence, and ends at a repair. Two habits make the entries shorter:

Read the refusal before acting. Each sentence names a different repair, and a refusal about authorization or inventory is not repaired by waiting.
Remember that an alias resolves to exactly one route. When that route refuses, its refusal is what the caller receives, so the sentence in the response body is a statement about one destination — the one brama aliases prints next to the alias.