docs(openapi): declare the 429 and 500 every route can answer with

[Bccorb]

Closes #245.

What

openapi.json contained zero 429 responses. Seventeen route definitions attach a per-flow limiter and every route sits behind dynamicRateLimit, so a 429 was reachable on effectively every endpoint and documented on none. The 500 from the top-level error handler had the same cause and was declared only on the 37 routes whose handlers happened to mention it.

src/generated/api.ts is emitted from the spec and committed, so a consumer reading it, or generating their own client, got a response union with neither case in it and would write code that cannot see them.

How

defineRoute adds both to every route it registers, which is the precedent the issue points at: it already injects the 400 ValidationErrorSchema for any route that validates a request. A route that declares one of them itself keeps its own, the same rule the 400 injection follows.

Both are declared as ErrorSchema, and that is true rather than aspirational: the limiters send TOO_MANY_REQUESTS_BODY, which is { error }, and the error handler sends { error: 'Internal server error' }.

All 90 operations now carry both. openapi.json and src/generated/api.ts are regenerated with npm run generate:api, which is most of the diff.

No runtime change

These responses feed registry.registerPath only. Runtime response validation in wrappedHandler reads schemas.response directly, which this does not touch, so no route starts or stops validating anything, and no body changes.

The CORS 403, deliberately left out

The issue also suggests the CORS 403 in the same pass. It is excluded, because declaring it would document something untrue: that handler answers res.status(403).json({ message: 'CORS policy does not allow this origin.' }), with no error field, so it does not match the canonical shape that docs/security-posture.md and tests/unit/routes/errorShapeCoverage.spec.ts describe as invariant. That test only inspects declared responses, which is why it never caught it.

Fixing it means changing a response body rather than documenting one, which is a behavior change and wants its own review. Say the word and I will file it.

Tests

The existing defineRoute spec asserted the exact default response object, so it now asserts the 200 alongside the two injected statuses. One test added for a route declaring its own 429, which must survive untouched. tests/unit/openapi/generatedContract.spec.ts passes, so the committed spec and the route definitions agree.

Checks

• npm run typecheck, npm run lint, npm run format:check, npm run build: clean
• npm run test:run: 114 files, 1362 passed, 1 skipped, 1 todo
• npm run coverage: 98.81% statements, 96.08% branches, 98.97% functions, 99.01% lines, all above threshold