Error Handling inside Internet Computer

This Page is Still Work in Progress

When a user calls a canister method, the response contains the following information. If the Internet Computer succeeded in running the canister method without any errors, then the response contains

status (text): replied
reply

If the Internet Computer generated any errors while processing the request, then the response contains

status (text): rejected
reject_code (nat)
reject_message (text)
error_code (text)

More details on the response structure can be found in the interface spec. There are a few dozen types of errors generated internally in the Internet Computer. Whenever an error is generated, it contains a 3-digit error code and a message describing the error. These list of error codes might change in the future as new features are added to the Internet Computer. If the error code is returned directly to the client, the client will have a tough time in responding to each of the error codes. To make the client's job easy, the response additionally includes a 1-digit reject code, which is same as the most significant digit of the error code.

Error Codes

SubnetOverSubscribed: StatusCode 101

This error is raised when installing a new canister or increasing memory allocation in the canister, and no compute allocation or memory capacity is left in the subnet.

MaxNumberOfCanistersReached: StatusCode 102

There is an option in the NNS registry to set a max limit on the number of canisters in a subnet. When a new canister is created, the subnet checks if this maximum limit is reached and throws an error accordingly. Currently, we don’t limit the number of canisters in a subnet.

CanisterOutputQueueFull: StatusCode 201

Internet Computer allows one canister to call another canister. These outgoing inter-canister canister calls are placed in the output queues of the canister. There is a currently a limit of 500 messages per output queue. CanisterOutputQueueFull error is thrown when this limit is reached.

IngressMessageTimeout: StatusCode 202

A user can call a method of a canister by sending an ingress message. The ingress messages go through consensus protocol. The ingress messages that are accepted by the consensus layer are pushed into ingress queue of the corresponding canister. The canister processes the messages in its ingress queue in order. If the system is quite loaded and if a message stays in the ingress queue for over 5 minutes, then IngressMessageTimeout error is thrown.

CanisterNotFound: StatusCode 301

When a user/canister calls a canister which is not found, CanisterNotFound error is thrown.

CanisterMethodNotFound: StatusCode 302

Each canister exposes a few methods that can be invoked by anyone. When a user/canister calls another canister, they need to specify a method to be invoked in the target canister. If this method is not found in the target canister, CanisterMethodNotFound error is thrown.

CanisterAlreadyInstalled: StatusCode 303

When anyone attempts to create a new canister, they can optionally specify a canister id that is to be used for the newly created canister. If the specified canister id is already taken (another canister exists with the specified canister id), then CanisterAlreadyInstalled error is thrown.

CanisterWasmModuleNotFound: StatusCode 304

A canister can be installed in a two step process. In the first step, a canister is created in a subnet and alloted a canister id. At this point, the canister is empty and does not contain any code. In the second step, the controller of the canister can install a Wasm module in the canister. If anyone sends an update/query call to the canister before the wasm module is installed, then CanisterWasmModuleNotFound error is thrown.

InsufficientTransferFunds: StatusCode 401

This error code is deprecated and currently not used anywhere. Earlier, one canister can transfer ICP to another canister. If a canister tries to send more ICP than it owns, InsufficientTransferFunds is thrown. It is later decided that all ICP holdings should be maintained in a ledger in the Network Nervous System, and the only way to transfer is to make a transaction in the ledger. As one canister can no longer transfer ICP to another canister, this error code is deprecated.

InsufficientMemoryAllocation: StatusCode 402

The controller of a canister can specify a limit on how much memory the canister could use. If this memory allocation is too low for the canister to function properly, then InsufficientMemoryAllocation error is thrown.

InsufficientCyclesForCreateCanister: StatusCode 403

When anyone tries to create a new canister, they need to spend at least 2 trillion cycles. If they do not own these funds, then InsufficientCyclesForCreateCanister error is thrown.

CanisterOutOfCycles: StatusCode 501

Each canister stores some cycles. When anyone sends a message to a canister, the canister spends a few cycles from its account to process the message. When someone sends a message and the canister doesn’t have enough cycles to process the message, CanisterOutOfCycles error is thrown.

CanisterTrapped: StatusCode 502

This error is thrown if the canister panicked somewhere or throws an error.

CanisterCalledTrap: StatusCode 503

This error is thrown if the canister explicitly decided to call System API ic0.trap method.

CanisterContractViolation: StatusCode 504

This error is thrown when a canister makes a System API call that is not allowed in that context. For example, when responding to a query call, a canister cannot call System API to check how many cycles are there in the query call.

CanisterInvalidWasm: StatusCode 505

When anyone is installing or upgrading a canister and supplies an invalid WASM module, CanisterInvalidWasm error is thrown.

CanisterOutOfMemory: StatusCode 507

A canister is allowed to reserve some memory for its usage. If a canister didn’t reserve memory before and is using memory beyond the subnet’s capacity, SubnetOverSubscribed error is thrown.

CanisterStopped: StatusCode 508

This error is thrown when someone calls a canister that is already stopped.

CanisterStopping: StatusCode 509

This error is thrown when someone calls a canister that is stopping.

CanisterNotStopped: StatusCode 510

Only a canister that is in stopped state can be deleted. If someone tries to delete a canister that is not in the stopped state, CanisterNotStopped error is thrown.

CanisterStoppingCancelled: StatusCode 511

Stopping a canister takes time. If someone restarts the canister during this time, CanisterStoppingCancelled error is thrown.

CanisterInvalidController: StatusCode 512

A canister is allowed to have a controller who has special rights over the canister. For example, the controller can call the management canister to upgrade its canister. When someone sends a management message to management canister without being the controller, CanisterInvalidController error is thrown.

CanisterFunctionNotFound: StatusCode 513

The error will be returned when we attempt to invoke a callback function that does not exist in the Wasm’s function table.

CanisterNonEmpty: StatusCode 514

Once someone installs a canister, they cannot install the same canister again. They can either upgrade or reinstall the canister. If someone tries to install an already installed canister, CanisterNonEmpty error is thrown.

CertifiedStateUnavailable: StatusCode 515

When a new node joins a subnet or when a node rejoins a subnet after some downtime, the node spends some time to sync the blockchain. Until the node syncs the certified state, it cannot serve queries. If the node gets a query before syncing the certified state, CertifiedStateUnavailable error is thrown. This error is temporary until the node catches up.

CanisterRejectedMessage: StatusCode 516

A canister can explicitly reject an incoming message by calling SystemAPI ic0.msg_reject. For example, A canister could reject a message because it doesn’t allow certain principals to use an endpoint, or has rate limiting.

InterCanisterQueryLoopDetected: StatusCode 517

When responding to a query/update call, a canister can make an inter-canister call to another canister. When responding to a query call, if canister X calls canister Y, and then canister Y cannot calls back Canister X, an InterCanisterQueryLoopDetected error is thrown. This error is thrown only for inter-canister query calls. An inter-canister loop is acceptable when responding to update calls.

UnknownManagementMessage: StatusCode 518

Inside each subnet, there is a special canister called management canister with predefined methods. If someone calls a management canister and specifies a method

InvalidManagementPayload: StatusCode 519

When anyone calls a management canister with an invalid payload, InvalidManagementPayload error is thrown.

InsufficientCyclesInCall: StatusCode 520

A canister can send cycles to another canister by making an update call with cycles attached. The recipient can choose to accept some of the cycles in the update call. The rest of the cycles are returned to the sender. InsufficientCyclesInCall error is thrown when the recipient is trying to accept more cycles than what is included in the call.

CanisterWasmEngineError: StatusCode 521

CanisterWasmEngineError error is thrown by the Internet Computer if WASM runtime library throws any error.

CanisterInstructionLimitExceeded: StatusCode 522

A canister has a limit on the number of instructions it can execute when responding to a query/update call. The limit is 5 Billion instructions when deterministic time slicing is not enabled. The limit is 30 Billion instructions when the deterministic time slicing feature is enabled. If a canister executes more instructions, then CanisterInstructionLimitExceeded error is thrown.

CanisterInstallCodeRateLimited: StatusCode 523

After a canister is created, the controller of the canister can upgrade the WASM code inside the canister. If the controller upgrades the canister too many times or if the install_code has a lot of instructions, then CanisterInstallCodeRateLimited error is thrown.

CanisterMemoryAccessLimitExceeded: StatusCode 524

A canister can store up to 32 GB of memory. In a single canister call, the canister is allowed to access up to 8 GB of memory. If a canister accesses more memory than the limit in a single canister call, CanisterMemoryAccessLimitExceeded error is thrown.