Error Handling and Return Codes

Use this page when you need one compact reference for how success and failure are represented in the C SDK.

Success baseline

TSDK_SUCCESS is the canonical success code and is defined as 0UL.

Use it for:

• successful tsdk_return(...)
• success checks after most syscalls
• success checks on the callee error channel returned through tsys_invoke

Local program failure

Use tsdk_revert(error_code) when your program detects an invalid condition and wants to terminate with a local error.

Typical examples:

• instruction payload too short
• invalid account index
• unexpected instruction tag
• failed precondition before a syscall

Successful termination

Use tsdk_return(return_code) when the program has completed successfully and wants to exit.

In most application-level code, the return code should be TSDK_SUCCESS.

Syscall error pattern

Most syscalls return a single ulong status:

ulong rc = tsys_account_resize( account_idx, 128UL );
if( rc != TSDK_SUCCESS ) tsdk_revert( rc );

CPI error pattern

tsys_invoke returns two different statuses:

• return value: syscall-level result
• invoke_err_code: callee-level result

Use both:

ulong invoke_err = 0UL;
ulong invoke_result = tsys_invoke( payload, payload_sz, target_program_idx, NULL, &invoke_err );

if( invoke_result != TSDK_SUCCESS ) tsdk_revert( invoke_result );
if( invoke_err    != TSDK_SUCCESS ) tsdk_revert( invoke_err );

Wrapper-level CPI validation failures

The current C wrapper can revert before issuing the CPI syscall if the auth descriptor is malformed or invalid.

Examples include:

• bad auth magic
• invalid account indices in auth or deauth lists
• auth entries for accounts not owned by the current program

Recommended error strategy

Situation	Recommended handling
Bad instruction layout	Revert with a local program error code.
Invalid index or ownership	Revert with a local program error code.
Failed syscall	Revert with the syscall return code, unless you intentionally remap it.
Failed CPI callee	Revert with invoke_err, unless you intentionally remap it.

Notes

• Do not mix up program-level validation errors with runtime or syscall return codes.
• Do not ignore the second result channel from tsys_invoke.
• Prefer a small local error-code namespace per program for validation failures, then bubble up syscall and CPI runtime codes directly when that is the clearest behavior.