Domain errors

Domain errors

Use a named error family to describe an exceptional outcome without mixing it with the successful result.

Declare an error family

main.expec

type Account {
  id: Text
}
error type AccountError {
  code: "duplicate-account" | "invalid-email"
  email: Text
}
function createAccount(email: Text) returns Account fails with AccountError

The successful result remains Account. fails with AccountError declares a possible exceptional outcome. It does not cause every invocation to fail.

An error family is a record marked error type. It needs a required code field whose type is a closed, nonempty set of Text literals. Do not give that field a default, make it optional or declare it as unrestricted Text. Repeated equivalent codes are invalid. Other fields describe the payload.

Construct error data

main.expec

error type AccountError {
  code: "duplicate-account" | "invalid-email"
  email: Text
}
examples {
  fixture duplicate: AccountError = AccountError {
    code: "duplicate-account",
    email: "reader@example.test",
  }
}

Constructing error data is not raising an exception. There is no source-language throw statement. Runtime implementation and the selected output profile own how declared failures are represented and raised.

A callable may return an error value as ordinary data instead. That is different from listing the family in fails with.

Generic failures and aliases

main.expec

error type Rejected<T> {
  code: "rejected"
  value: T
}
type TextRejection = Rejected<Text>
function accept(value: Text) returns Nothing fails with TextRejection

Imports, aliases and generic substitution use the normal type rules. Multiple failure families/applications are comma-separated. Listing equivalent failures twice is invalid. An ordinary record without error is not an exceptional contract, and a public callable must not expose a local error family.

Related: Capabilities and contracts · Types · Output support