> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kviria.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Status codes and error messages - built for self-correction.

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](/api/agent)) |
| `402`  | Free daily turns used up                          | Top up ([payments](/api/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](https://kviria.com/tool-definition.json).

## 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