Errors and limits

The error body

Every JSON error has the same shape. The error value is a short English string, for logs, not for the student.

{ "error": "unauthorized" }

Show a Turkish message of your own to the student. Do not show the error value.

Status codes

Status	Where	Value of `error`	What to do
`400`	`POST /api/chat/send`	`empty message`	The body had no text and no image. Block the send in the user interface.
`401`	any `/api` route	`unauthorized`	Refresh the Supabase session once, then retry once.

There is no 403, no 404 for a valid route, and no 429. The API has no rate limit today. Do not depend on that.

Schema validation errors

A body that breaks the request schema is rejected by the validator, before the route handler runs. This response has a different shape. error is an array of issues, not a string:

{
  "success": false,
  "data": { "dailyHours": 40 },
  "error": [
    {
      "code": "too_big",
      "maximum": 16,
      "path": ["dailyHours"],
      "message": "Too big: expected number to be <=16"
    }
  ]
}

Parse error as a value of unknown shape. Read success first: false and a 400 status mean a schema rejection. The messages are English, and they are for the developer. Read Profile and onboarding for the field constraints.

Failures inside the stream

POST /api/chat/send returns 4xx only before the stream starts. After the stream starts, the status is 200, and a failure arrives as an SSE error event:

event: error
data: {"error":"chat failed"}

Treat this as a failed turn. Show a retry control, then call GET /api/chat/history to resynchronize. Read Stream a chat answer.

Degraded, not failed

Several parts of a turn can fail without failing the turn. The student sees a normal answer, with less context:

Part	On failure
Retrieval over the coaching corpus	The turn continues with no retrieved context.
The YÖK Atlas tool server	The turn retries without those tools.
Tracing and usage logging	The turn continues. Nothing is reported to the client.
Push delivery	The message stays in the history.

Only the model stream itself can fail a turn. The client cannot detect a degraded turn, and does not need to.

Limits

Limit	Value	Where
Message length	8000 characters	`message` in `POST /api/chat/send`
History window	60 messages	`GET /api/chat/history`
Model call timeout	60 seconds	one turn
Model steps per turn	5	one turn
Profile subject lists	16 items, 64 characters each	`PATCH /api/profile`
Scratchpad notes	2000 characters	internal, model-maintained
Rate limit	none today	—

Set the client request timeout for POST /api/chat/send to at least 90 seconds. A turn with several tool steps takes longer than a plain answer.

Retries

Never retry POST /api/chat/send automatically. The student message is persisted before the model runs, so an automatic retry duplicates it in the history. Retry only when the student asks for it.

GET /api/me, GET /api/chat/history, and GET /health are read-only, and safe to retry. PATCH /api/profile writes the same values again, so it is also safe to retry.

Start here

Build

Understand

For agents

The error body

Status codes

Schema validation errors

Failures inside the stream

Degraded, not failed

Limits

Retries

​The error body

​Status codes

​Schema validation errors

​Failures inside the stream

​Degraded, not failed

​Limits

​Retries

The error body

Status codes

Schema validation errors

Failures inside the stream

Degraded, not failed

Limits

Retries