Errors

An error names its cause in error, so your agent can fix the call itself. Answers about places that found nothing are not errors: see the end of this page.

By status

Status	`error`	What to do
400	`invalid_request`	The `message` names the field to fix, such as `search needs a kind`. Fix the request and call again
400	`transcript_removed`	Kviria no longer reads the user’s words. Parse them into the request’s fields and call again
400	`invalid_state`	The state was altered. Start again with an empty state
400	`anchor_required`	Send the user’s position on the first call of a conversation
400	`unsupported_field`, `invalid_body`	The `message` names the problem. Fix it and send the call once more
400	`payment_rejected:` and a reason, or `payment_settle_failed`	The payment did not go through. `already_claimed`: that payment was already used
400	`invalid JSON body`, or a message about the agent name	Fix the request
401	`unauthorized`	No key or token, or one Kviria does not know. Send a key, or connect with OAuth. See Connect and pay
402	`free_daily_limit_exhausted`	Today’s free turns are used up. Top up, then send the call again
413	`payload_too_large`	The body is over 16 KB (64 KB on the MCP server)
429	`turn_minute_limit`	Too many turns this minute. Wait for `Retry-After`
429	`payment_rate_limit`	More than 5 payments this minute. Wait for `Retry-After`
429	`payment_verify_capacity`	Payments cannot be checked right now. Try again later
429	`service_busy`	Kviria is under heavy demand. Wait for `Retry-After`
500	`Server Error`	Try again after a short pause

Bodies that carry a state

The bodies of invalid_body, invalid_request, unsupported_field, transcript_removed, anchor_required and invalid_state have three fields: error, message and state. Send that state on the next call. After invalid_state it is empty, so the conversation starts again.

{
  "error": "unsupported_field",
  "message": "candidates is no longer accepted: send back the state field of the previous response",
  "state": ""
}

Messages you may see

`message`	Fix
`search needs a kind`, `across needs a place`, and the other types’ needs	Send the field the type needs. Each type’s needs are in the Agent endpoint
`transcript is no longer accepted: ...`	Parse the user’s words into the request’s fields
`anchor {lat, lng} is required on the first call of a conversation`	Send the user’s position
`intent is no longer accepted: send the request's fields (request, place, kind, ...) at the top level`	Send the fields at the top level of the body
`candidates is no longer accepted: send back the state field of the previous response`	Send the `state` instead. The same message names `references` and `frame`
`unknown field(s): ...`	Remove the fields it names
`state is not a state this service issued (...); start again with an empty state`	Send an empty `state`

Answers that are not errors

These come back with status 200:

none: Kviria looked and found nothing. It may carry the absent category.
none with an out_of_coverage evidence entry: the position is outside coverage. The turn is never charged. Tell the user instead of trying other positions.
unclear: the request is not specific enough. Ask the user to say more.

Get started

Guides

Concepts

Reference

By status

Bodies that carry a state

Messages you may see

Answers that are not errors

​By status

​Bodies that carry a state

​Messages you may see

​Answers that are not errors

By status

Bodies that carry a state

Messages you may see

Answers that are not errors