Module 0x1::error

This module defines a set of canonical error codes which are optional to use by applications for the abort and assert! features.

Canonical error codes use the 3 lowest bytes of the u64 abort code range (the upper 5 bytes are free for other use). Of those, the highest byte represents the error category and the lower two bytes the error reason. Given an error category 0x1 and a reason 0x3, a canonical abort code looks as 0x10003.

A module can use a canonical code with a constant declaration of the following form:

///  An invalid ASCII character was encountered when creating a string.
const EINVALID_CHARACTER: u64 = 0x010003;

This code is both valid in the worlds with and without canonical errors. It can be used as a plain module local error reason understand by the existing error map tooling, or as a canonical code.

The actual canonical categories have been adopted from Google’s canonical error codes, which in turn are derived from Unix error codes see here. Each code has an associated HTTP error code which can be used in REST apis. The mapping from error code to http code is not 1:1; error codes here are a bit richer than HTTP codes.

• Constants
• Function canonical
• Function invalid_argument
• Function out_of_range
• Function invalid_state
• Function unauthenticated
• Function permission_denied
• Function not_found
• Function aborted
• Function already_exists
• Function resource_exhausted
• Function internal
• Function not_implemented
• Function unavailable
• Specification
  • Function canonical

Constants

Concurrency conflict, such as read-modify-write conflict (http: 409)

const ABORTED: u64 = 7;

The resource that a client tried to create already exists (http: 409)

const ALREADY_EXISTS: u64 = 8;

Request cancelled by the client (http: 499)

const CANCELLED: u64 = 10;

Internal error (http: 500)

const INTERNAL: u64 = 11;

Caller specified an invalid argument (http: 400)

const INVALID_ARGUMENT: u64 = 1;

The system is not in a state where the operation can be performed (http: 400)

const INVALID_STATE: u64 = 3;

A specified resource is not found (http: 404)

const NOT_FOUND: u64 = 6;

Feature not implemented (http: 501)

const NOT_IMPLEMENTED: u64 = 12;

An input or result of a computation is out of range (http: 400)

const OUT_OF_RANGE: u64 = 2;

client does not have sufficient permission (http: 403)

const PERMISSION_DENIED: u64 = 5;

Out of gas or other forms of quota (http: 429)

const RESOURCE_EXHAUSTED: u64 = 9;

Request not authenticated due to missing, invalid, or expired auth token (http: 401)

const UNAUTHENTICATED: u64 = 4;

The service is currently unavailable. Indicates that a retry could solve the issue (http: 503)

const UNAVAILABLE: u64 = 13;

Function canonical

Construct a canonical error code from a category and a reason.

public fun canonical(category: u64, reason: u64): u64

public fun canonical(category: u64, reason: u64): u64 {
  (category << 16) + reason
}

Function invalid_argument

Functions to construct a canonical error code of the given category.

public fun invalid_argument(r: u64): u64

public fun invalid_argument(r: u64): u64 {  canonical(INVALID_ARGUMENT, r) }

Function out_of_range

public fun out_of_range(r: u64): u64

public fun out_of_range(r: u64): u64 {  canonical(OUT_OF_RANGE, r) }

Function invalid_state

public fun invalid_state(r: u64): u64

public fun invalid_state(r: u64): u64 {  canonical(INVALID_STATE, r) }

Function unauthenticated

public fun unauthenticated(r: u64): u64

public fun unauthenticated(r: u64): u64 { canonical(UNAUTHENTICATED, r) }

Function permission_denied

public fun permission_denied(r: u64): u64

public fun permission_denied(r: u64): u64 { canonical(PERMISSION_DENIED, r) }

Function not_found

public fun not_found(r: u64): u64

public fun not_found(r: u64): u64 { canonical(NOT_FOUND, r) }

Function aborted

public fun aborted(r: u64): u64

public fun aborted(r: u64): u64 { canonical(ABORTED, r) }

Function already_exists

public fun already_exists(r: u64): u64

public fun already_exists(r: u64): u64 { canonical(ALREADY_EXISTS, r) }

Function resource_exhausted

public fun resource_exhausted(r: u64): u64

public fun resource_exhausted(r: u64): u64 {  canonical(RESOURCE_EXHAUSTED, r) }

Function internal

public fun internal(r: u64): u64

public fun internal(r: u64): u64 {  canonical(INTERNAL, r) }

Function not_implemented

public fun not_implemented(r: u64): u64

public fun not_implemented(r: u64): u64 {  canonical(NOT_IMPLEMENTED, r) }

Function unavailable

public fun unavailable(r: u64): u64

public fun unavailable(r: u64): u64 { canonical(UNAVAILABLE, r) }

Specification

Function canonical

public fun canonical(category: u64, reason: u64): u64

pragma opaque = true;
let shl_res = category << 16;
ensures [concrete] result == shl_res + reason;
aborts_if [abstract] false;
ensures [abstract] result == category;