Errors

Every non-2xx response has the same JSON body:

{ "error": { "code": "invalid_request", "message": "Field 'question' is required" } }

Status	error.code	Meaning
401	unauthorized	No credentials sent (Authorization or X-API-Key)
401	invalid_api_key	Unknown or revoked API key
401	invalid_token / token_expired	Supabase token malformed, from another project, or expired
404	unknown_case	The case does not exist
404	graph_unavailable	The case has no published graph yet (available: false)
404	node_not_found / cluster_not_found / key_not_found	Unknown node, cluster or key
404	search_unavailable	No dataset configured for the case
422	validation_error	Invalid body or query parameters (details in message)
429	rate_limited	Per-minute rate limit exceeded (chat is limited separately) — retry with backoff
500	internal_error	Unexpected server error
502 / 504	upstream_error / upstream_timeout	RAGFlow failed or timed out
503	docs_ask_unavailable	The docs assistant is not configured

code is a stable machine-readable string; message is for humans and may change.

In the SDK

import { VolApiError } from "@vol/sdk";

try {
  await vol.chat({ case: "papers", question: "…" });
} catch (e) {
  if (e instanceof VolApiError) console.error(e.status, e.code, e.message);
}

The SDK also understands FastAPI’s default { "detail": "…" } body and falls back to the HTTP status text. During streaming, failures after the first byte arrive as an error event instead of an HTTP status.