docs(openapi): declare the statuses routes can already answer

[rmyndharis]

What

The contract described the happy path and the timeout but almost nothing in between. This adds 125 declarations across eleven controllers. No runtime behaviour changes — every status added was already reachable before this PR.

Status	Routes	Error class
409	91	EngineNotReadyError
501	11	EngineNotSupportedError, ChannelMediaNotSupportedError
404	11	Message / Group / Channel / LabelNotFoundError
400	6	RecipientUnreachableError
403	6	EngineRefusedError

Follows #1163, which did the same for 503 alone. The generalisation is that thirteen error classes in src/common/errors map to a status through their NestJS base, not one.

The 409, which is most of it

Every adapter method calls ensureReady() before touching the socket or the page — 168 call sites — and that guard throws EngineNotReadyError. So any route that reaches an engine answers 409 when the session exists but has no live engine behind it. None of the 91 said so.

Ten routes already declared a 409, for an unrelated reason: a name already taken, a plugin already installed, a session already running. Those are semantic conflicts rather than a missing engine, and the two sets do not overlap, so the new declaration carries its own description distinguishing them.

How the route set was derived

Handler → service → both adapters, per route. Two things are worth stating because they changed the answer:

Reachability is type-resolved, not name-matched. An earlier pass keyed on the method name alone and wrongly flagged GET /plugins/catalog: PluginsService.getCatalog shares a name with CatalogService.getCatalog, and only the latter touches an engine. Resolving this.<prop>.<method>() through the controller's constructor types drops it, and re-running the corrected predicate reports zero remaining mismatches.

The predicate was checked against a known answer. Of the 52 routes declaring 503, it flags 49 as engine-reaching and excludes exactly the three whose 503 comes from elsewhere — the readiness probe and the two media-conversion routes. That is the expected split, which is what makes the 91 trustworthy.

"Session-scoped" was deliberately not used as the criterion, though it was how the scale was first measured: GET /sessions/{id}/config sits under that prefix and never reaches an engine, so keying on the path shape would have published a status that cannot occur.

Two structural choices

Descriptions live in one shared module (src/common/openapi/engine-status-responses.ts) rather than per controller. The text describes engine behaviour, not any one route's, so eleven copies would drift the moment one was reworded — which is how the contract fell behind in the first place.

They are applied per handler, not at class level. Seven of the eleven controllers are 100% engine-touching, so a class-level @ApiResponse would have cut the diff from 92 lines to 7. It was rejected: a future route added to one of those controllers would silently inherit a 409 whether or not it touches an engine, which is the same rot as a hand-maintained list, only harder to notice.

The one that mattered most

On the four group participant writes, the undeclared 403 is the status separating a batch WhatsApp refused outright from one that was applied with some members rejected — the latter is reported inside results on a 200. Those four now declare 200, 403, 409, 503.

Verification

openapi:check, lint, format:check, tsc --noEmit, build all exit 0; npm test passes 5119 tests across 300 suites. openapi.json regenerated with npm run openapi:export, never hand-edited. Status totals moved exactly as intended: 400 64→70, 403 21→27, 404 64→75, 409 10→101, 501 16→27, with 503 unchanged at 52.