Error messages & status codes
What each status means here and the exact body shape to expect.
Error messages & status codes
The standard failure body
{ "success": false, "message": "Human-readable reason" }Server-side failures add the underlying error text:
{ "success": false, "message": "Failed to export dataset", "error": "column "foo" does not exist" }A few older handlers use { "error": "Unauthorized" } instead of message. Check for both keys when you write a client.
400 Bad Request
The body was parseable but a value was rejected — an unknown dataset key, a grouping that does not exist for that dataset, a team name over 120 characters, a role that is not in MEMBER_ROLES. Nothing is written. Fix the value; do not retry as-is.
401 Unauthorized
No session: the jv_session cookie is missing, or the auth_sessions row behind it was revoked, expired after 24 hours of inactivity, or never existed. Redirect to /login — the login page carries the reason and returns the visitor to where they were.
A 401 is never a database problem. When the session could not be looked up at all the answer is 503, and the client retries rather than signing anybody out.
403 Forbidden
Signed in, not allowed. The message names what is required. Retrying with the same session will always fail.
404 Not Found
The id does not exist, or it exists and belongs to a route that is not public. On marketing pages a 404 renders the group not-found boundary with links back to the home page and the blog.
409 Conflict
A deliberate refusal with a reason. Example — requesting account deletion while work is still assigned:
{"success": false, "message": "Cannot request deletion: 3 tasks still assigned to you. Reassign or complete them first.", "assignedTasks": 3
}Duplicate-name cases behave the same way: creating a reward or achievement whose name already exists returns 409 with the offending name in the message.
429 Too Many Requests
Rate limited. Public form routes allow 5 requests a minute per IP. The auth routes have their own budgets — 20 login attempts per 15 minutes, 10 signups an hour, 5 reset mails an hour — keyed by IP and, where one was submitted, by email address. The response carries a Retry-After header with the seconds to wait; wait for it rather than retrying in a loop.
500 Internal Server Error
Unexpected. The message field says which operation failed ("Failed to build dashboard overview") and the error field carries the database or provider text. These are logged server-side with the same prefix, so quoting the message in a support request lets us find the log line.
503 Service Unavailable
The database did not answer — on Neon that is usually a sleeping compute waking up, which takes a few seconds. GET /api/auth/session and the auth actions answer 503 with a Retry-After header instead of presenting it as a credential failure. Retry; do not treat it as a sign-out.
Reading errors in the browser
The dashboard surfaces failures as toasts with the server message. If a toast says "Failed to X" with no detail, open the network tab and read the response body — the detail is there.