Errors and failures

Two different things can go wrong. A request can be refused, which returns an error at once. Or an action can run and fail, which ends it with a failure reason.

Error responsesCopy Anchor Link

Every response outside 2xx has the same body: an error object with a code, a message for people, and, for invalid_request, the field that failed.

Validation errorsCopy Anchor Link

Vene reports the first failing value. field is its dotted path, with array positions in brackets. Paths in an action's input start at input.

{
  "error": {
    "code": "invalid_request",
    "message": "Expected a two-letter state code",
    "field": "input.pharmacy.address.state"
  }
}

A missing value says Required. A field the schema does not define is refused too, and field names that field:

{
  "error": {
    "code": "invalid_request",
    "message": "Unrecognized key: \"pharmacy_phone\"",
    "field": "input.pharmacy_phone"
  }
}

Answers name their position in the request, such as answers[0].answer.value.

Failure reasonsCopy Anchor Link

An action that runs but cannot get a definite answer ends failed. Its result.failure_reason says why, and result.next_step says what you could do, when there is something.

A failure is not an error response. The action is readable as usual, with its calls and transcripts.

What succeeded meansCopy Anchor Link

succeeded means the place gave a definite answer, even when the answer is bad news. A pharmacy with no record of a prescription returns succeeded with fill_status: "not_found". A refused transfer returns succeeded with transfer_status: "refused" and a refusal_reason.

How calls endCopy Anchor Link

Each call in trail records how it ended. A call that ends without an answer does not end the action. Vene decides what to do next, such as calling back later.