The app has two kinds of server endpoints:
- Server functions (
createServerFn) back the app's own pages. They are TanStack Start RPCs, not a public API. Their errors travel through TanStack's channel:notFound(),redirect(), or a thrown error the page catches. /api/*server routes carry what isn't a page RPC: uploads, downloads and streams. Every error they return follows the contract below.
| Method | Path | Success |
|---|---|---|
POST |
/api/chats/:chatId/messages |
200 with a text/event-stream of the answer |
POST |
/api/chats/:chatId/answer |
200 with a text/event-stream of a new answer |
GET |
/api/chats/:chatId/files/:fileId |
200 with the file; images inline, everything else as a download |
messages takes multipart form data: content, model (one of the ids in src/lib/models.ts) and up to four files of at most 5 MB each. The first message creates the chat. Files go to R2 under chats/<chatId>/<fileId>; their text (read directly, or through ai.toMarkdown() for PDFs, images and Office files) is saved in D1 and sent to the model inside <file> tags.
answer takes { "model": "..." }, removes the answers after the latest user turn and streams a new one.
Both streams are Workers AI's SSE. Older models send data: {"response": "..."}; newer ones send OpenAI-style choices[0].delta with content and, for reasoning models, reasoning_content. A stream that stops early ends with event: void:limit or event: void:error. The server saves the answer, with its reasoning, once the stream finishes cleanly. src/lib/ai-stream.ts parses both shapes for the browser and the server.
Files are served with x-content-type-options: nosniff and content-security-policy: sandbox, so an uploaded HTML or SVG file never runs on the app's origin.
There are no accounts. The first page load sets a visitor cookie (a random UUID, HttpOnly, one year), and the first message ties the chat to it. Every route answers 404 for a chat owned by another visitor, the same as for a missing one, and 401 when the cookie is absent.
Every /api/* error is a 4xx or 5xx response with content-type: application/json and a flat body:
{
"code": "VALIDATION_ERROR",
"message": "Files can be up to 5 MB each.",
"issues": [{ "path": "files.0", "message": "Files can be up to 5 MB each." }]
}codeand the status are what a client branches on. Each code maps to exactly one status.messageis a sentence for the person using the app. Clients show it and never parse it.issuescomes only withVALIDATION_ERROR: one{ path, message }per failed field,pathdotted (files.0) and""for the whole input.messagerepeats the first issue.traceIdcomes only withINTERNAL_SERVER_ERROR. It is the request'scf-rayid through Cloudflare's edge, or a random UUID locally, and theapi.failedlog carries the same value (observability.md).- A body never holds stack traces, SQL, internal hostnames or the validation library's own wording. Headers such as
retry-aftercarry anything else.
code |
Status | When |
|---|---|---|
VALIDATION_ERROR |
400 | The input doesn't match the schema, a file is over 5 MB or empty, or the body is too big |
UNAUTHORIZED |
401 | Credentials are missing, invalid or expired: today, no visitor cookie |
FORBIDDEN |
403 | The resource is visible, but this identity may not do that. Unused today |
NOT_FOUND |
404 | The chat or file doesn't exist, the id is malformed, or another visitor owns the chat |
CONFLICT |
409 | The request conflicts with the resource's current state. Unused today |
TOO_MANY_REQUESTS |
429 | A usage limit was reached; wait for retry-after seconds |
INTERNAL_SERVER_ERROR |
500 | An unexpected failure; traceId finds it in the logs |
SERVICE_UNAVAILABLE |
503 | A dependency isn't configured or reachable, such as AI before pnpm connect |
- Build every error with
errorResponse()fromapps/web/src/server/error-response.ts, and every validation failure withvalidationError()fromsrc/lib/api.ts. Never write error JSON by hand. - Wrap every
/api/chats/$chatId/*handler inchatRoute()(src/server/api.server.ts). It answers404for a malformed id and401without a visitor, and an unexpected throw still answers500with atraceIdand is logged asapi.failed. - The browser reads an error body only through
readApiError()insrc/lib/api.ts. - Success bodies carry the result directly. There is no
{ success, data }envelope. - Answer
404, not403, when the caller may not know the resource exists. - Add a code only when a client must react differently and the status alone can't tell it. Renaming or removing a published code is a breaking change.
apps/web/test/api.test.ts asserts the status and body of each error through the route handlers.