Errors - Kviria

Kviria’s error surface is machine-readable on purpose: an agent that can parse the failure can fix the request itself.

HTTP status codes

Status	Meaning	What your agent does
`400`	Invalid request - the message names the bad field	Fix the flagged field and retry once
`401`	No wallet sign-in	Build a `SIGN-IN-WITH-X` header (see the agent endpoint)
`402`	Free daily turns used up	Top up (payments), then retry
`413`	Body over 16 KB	Trim echoed candidates
`429`	Rate limit or heavy demand	Back off per `Retry-After`
`500`	Server error	Retry after a short delay

A 400 starting with siwx_invalid: means the sign-in itself was rejected (stale nonce, wrong domain, bad signature) - build a fresh one and retry once.

400 messages

A rejected request names the exact field to fix. The messages you will see:

Message	Fix
`transcript and intent are mutually exclusive`	Send exactly one of them
`one of "transcript" or "intent" is required`	Send one of them
`intent schema violation at <field>: <reason>`	Fix the flagged field, retry once
`transcript must be 2-1000 characters`	Send the user’s raw message as-is
`anchor must be {lat, lng} with finite numbers`	The anchor is required on every call
`candidates must be [{gers, name?, ...}] (max 50)`	Echo the previous array unchanged
`anchor_unresolved`	The intent’s anchor must be a `ref`, `name`, `index`, or `at` from Kviria’s own data, not a description
`street_unknown`	Street not in the covered area - tell the user

Treat a 400 as a conversation, not a dead end: fix, retry once. The authoritative schema lives in the tool definition.

Honest answers that are not errors

notFound - nothing matched (may carry the absent category)
clarify - the reference was too vague; ask the user
Outside beta coverage (San Francisco) - a notFound, not an error