Repository navigation
feat(web)!: flat { code, message } error contract; move rules/ under docs/rules/ - #2
Merged
Merged
Conversation
…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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 bycodeand status, instead of RFC 9457 problem+json.Error contract (32e648d)
Every
/api/*error is a 4xx/5xx withcontent-type: application/json:{ "code": "VALIDATION_ERROR", "message": "Pick a model.", "issues": [{ "path": "model", "message": "Pick a model." }] }type,title,detail,instance,statusmember orapplication/problem+json.issuesonly onVALIDATION_ERROR, one{ path, message }per failed field. Zod's own wording never leaks.traceIdonly onINTERNAL_SERVER_ERROR. It is thecf-rayid at the edge, a random UUID locally, and theapi.failedlog carries the same value.server/error-response.ts(errorResponse(), replacesproblemResponse()).src/lib/api.tsis the one client parse point (readApiError(), Zod-validated) and builds validation bodies (validationError()). It replaceslib/api-problem.ts. The composer showsmessageand branches only oncode: a 500 toast adds thetraceIdas a reference.Behavior changes a caller will notice:
PAYLOAD_TOO_LARGE(413) is gone. Oversized or empty files and an oversized body answer400 VALIDATION_ERROR, with the field inissues.401 UNAUTHORIZEDinstead of400 VALIDATION_ERROR.429keepsretry-after; theretryAtbody member is gone.Tests:
test/api.test.tscalls 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), plusreadApiError()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 todocs/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 verifypasses (36 tests).pnpm e2epasses.vp devWorker, curl returned the bodies the tests assert (404, 401, 400 withissues).🤖 Generated with Claude Code