Skip to content

feat(web)!: flat { code, message } error contract; move rules/ under docs/rules/ - #2

Merged
SweetRetry merged 2 commits into
mainfrom
feat/flat-error-contract
Oct 22, 2026
Merged

SweetRetry merged 2 commits into
mainfrom
feat/flat-error-contract

Conversation

@SweetRetry

Copy link
Copy Markdown
Owner

Who this is for

Anyone calling /api/* (today the chat UI) and the next engineer adding a route. Errors now follow the shared API contract: a flat JSON body that clients branch on by code and status, instead of RFC 9457 problem+json.

Error contract (32e648d)

Every /api/* error is a 4xx/5xx with content-type: application/json:

{ "code": "VALIDATION_ERROR", "message": "Pick a model.", "issues": [{ "path": "model", "message": "Pick a model." }] }
  • No type, title, detail, instance, status member or application/problem+json.
  • issues only on VALIDATION_ERROR, one { path, message } per failed field. Zod's own wording never leaks.
  • traceId only on INTERNAL_SERVER_ERROR. It is the cf-ray id at the edge, a random UUID locally, and the api.failed log carries the same value.
  • Codes are the eight of the shared contract, one status each, in server/error-response.ts (errorResponse(), replaces problemResponse()).
  • src/lib/api.ts is the one client parse point (readApiError(), Zod-validated) and builds validation bodies (validationError()). It replaces lib/api-problem.ts. The composer shows message and branches only on code: a 500 toast adds the traceId as a reference.

Behavior changes a caller will notice:

  • PAYLOAD_TOO_LARGE (413) is gone. Oversized or empty files and an oversized body answer 400 VALIDATION_ERROR, with the field in issues.
  • A missing visitor cookie answers 401 UNAUTHORIZED instead of 400 VALIDATION_ERROR.
  • 429 keeps retry-after; the retryAt body member is gone.

Tests: test/api.test.ts calls the route handlers the way a client does and asserts the status and a literal body for every error path (404 malformed id, 401, 404 foreign chat, 404 missing file, 400 with issues, 400 wrong type, 400 oversized body, 503, 429 + retry-after, 500 + traceId + log, answer 400/404), plus readApiError() on contract and non-contract bodies. Only the platform modules (Void bindings, cloudflare:workers, TanStack's cookie reader) are faked.

Docs: docs/api.md (contract, all eight codes, rules), observability.md, architecture.md, CONTEXT.md (Problem becomes API error), READMEs, blog sentences that describe the format.

Rules move (ecf48ed)

rules/ moved to docs/rules/. The Zod scan's root path, zod:check, the knip ignore, AGENTS.md routing, READMEs, guardrails links and blog layout trees follow it.

Verification

  • pnpm verify passes (36 tests).
  • pnpm e2e passes.
  • Against a live vp dev Worker, curl returned the bodies the tests assert (404, 401, 400 with issues).

🤖 Generated with Claude Code

SweetRetry and others added 2 commits October 22, 2026 16:15
…rror body

Every /api/* error now answers application/json with { code, message, issues?, traceId? }.
issues lists failed fields only on VALIDATION_ERROR; traceId (the cf-ray id, or a random UUID
locally, also logged as api.failed) comes only with INTERNAL_SERVER_ERROR.

- errorResponse() in server/error-response.ts replaces problemResponse(); codes are the eight
  of the shared API contract, one status each.
- lib/api.ts is the one client parse point (readApiError) and builds validation bodies.
- PAYLOAD_TOO_LARGE (413) folds into VALIDATION_ERROR (400) with the field in issues.
- A missing visitor cookie answers 401 UNAUTHORIZED instead of 400.
- 429 keeps retry-after; the retryAt member is gone.
- Route-level tests assert status and literal body for every error path.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Engineering rules now live with the rest of the system knowledge. The Zod scan, knip ignore,
AGENTS.md routing, READMEs, guardrails and blog layout trees point at the new path.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@SweetRetry
SweetRetry merged commit ecf48ed into main Oct 22, 2026
2 checks passed
@SweetRetry
SweetRetry deleted the feat/flat-error-contract branch October 22, 2026 08:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant