From 357fc383ca8a56343131dc7ca354173412d70a3e Mon Sep 17 00:00:00 2001 From: Ognjen Maric Date: Tue, 15 Apr 2025 10:35:17 +0200 Subject: [PATCH 1/3] A proposal for a system API exposing error codes to canisters --- docs/references/ic-interface-spec.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/references/ic-interface-spec.md b/docs/references/ic-interface-spec.md index 4637041a4e..002b0b078a 100644 --- a/docs/references/ic-interface-spec.md +++ b/docs/references/ic-interface-spec.md @@ -1158,7 +1158,7 @@ When canisters explicitly reject a message (see [Public methods](#system-api-req ### Error codes {#error-codes} -Implementations of the API can provide additional details for rejected messages in the form of a textual label identifying the error condition. API clients can use these labels to handle errors programmatically or suggest recovery paths to the user. The specification reserves error codes matching the regular expression `IC[0-9]+` (e.g., `IC502`) for the DFINITY implementation of the API. +Implementations of the HTTPS and System APIs can provide additional details for rejected messages in the form of a textual label identifying the error condition. API clients and canisters can use these labels to handle errors programmatically or suggest recovery paths to the user. In the HTTPS API, the specification reserves error codes matching the regular expression `IC[0-9]+` (e.g., `IC502`) for the DFINITY implementation of the API. ### Status endpoint {#api-status} @@ -1480,6 +1480,7 @@ defaulting to `I = i32` if the canister declares no memory. ic0.msg_reject_code : () -> i32; // Ry Rt CRy CRt ic0.msg_reject_msg_size : () -> I ; // Rt CRt ic0.msg_reject_msg_copy : (dst : I, offset : I, size : I) -> (); // Rt CRt + ic0.msg_error_code : () -> i32; // Rt CRt ic0.msg_deadline : () -> i64; // U Q CQ Ry Rt CRy CRt @@ -1647,6 +1648,10 @@ The canister can access an argument. For `canister_init`, `canister_post_upgrade The reject message. Traps if there is no reject message (i.e. if `reject_code` is `0`). +- `ic0.msg_error_code : () → i32` + + The error code. Traps if there is no reject message (i.e. if `reject_code` is `0`). + - `ic0.msg_deadline : () -> i64` The deadline, in nanoseconds since 1970-01-01, after which the caller might stop waiting for a response. From d8209ffae8345739e03fda91f880a760e67f794d Mon Sep 17 00:00:00 2001 From: oggy-dfin <89794951+oggy-dfin@users.noreply.github.com> Date: Tue, 15 Apr 2025 15:58:43 +0200 Subject: [PATCH 2/3] Update docs/references/ic-interface-spec.md Co-authored-by: mraszyk <31483726+mraszyk@users.noreply.github.com> --- docs/references/ic-interface-spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/references/ic-interface-spec.md b/docs/references/ic-interface-spec.md index 002b0b078a..22f07ea322 100644 --- a/docs/references/ic-interface-spec.md +++ b/docs/references/ic-interface-spec.md @@ -1650,7 +1650,7 @@ The canister can access an argument. For `canister_init`, `canister_post_upgrade - `ic0.msg_error_code : () → i32` - The error code. Traps if there is no reject message (i.e. if `reject_code` is `0`). + The error code. Traps if there is no error code (i.e. if `reject_code` is `0`). - `ic0.msg_deadline : () -> i64` From 2f40a10f622d79b306d2f419f0a1f6e8000129f2 Mon Sep 17 00:00:00 2001 From: Ognjen Maric Date: Tue, 15 Apr 2025 16:00:24 +0200 Subject: [PATCH 3/3] Fix textual labels vs error codes --- docs/references/ic-interface-spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/references/ic-interface-spec.md b/docs/references/ic-interface-spec.md index 22f07ea322..4b23696c0d 100644 --- a/docs/references/ic-interface-spec.md +++ b/docs/references/ic-interface-spec.md @@ -1158,7 +1158,7 @@ When canisters explicitly reject a message (see [Public methods](#system-api-req ### Error codes {#error-codes} -Implementations of the HTTPS and System APIs can provide additional details for rejected messages in the form of a textual label identifying the error condition. API clients and canisters can use these labels to handle errors programmatically or suggest recovery paths to the user. In the HTTPS API, the specification reserves error codes matching the regular expression `IC[0-9]+` (e.g., `IC502`) for the DFINITY implementation of the API. +Implementations of the HTTPS and System APIs can provide additional details for rejected messages in the form of an error code identifying the error condition. API clients and canisters can use these codes to handle errors programmatically or suggest recovery paths to the user. In the HTTPS API, the error codes are represented using textual labels in the state tree. For these labels, the specification reserves error codes matching the regular expression `IC[0-9]+` (e.g., `IC502`) for the DFINITY implementation of the HTTPS API. ### Status endpoint {#api-status}