Error Codes

This guide documents the error identifiers returned by Portal’s MPC (Multi-Party Computation) operations. These errors follow a string-based identifier system that provides clear, meaningful error categorization.

Error structure

MPC operations return errors in a standardized JSON format:

{
  "error": {
    "id": "RPC_OP_FAILED",
    "message": "Failed to send transaction: insufficient funds for gas * price + value: balance 1109136374275907, tx cost 2726006969664281, overshot 1616870595388374",
    "code": 123  // Deprecated - do not use!
  }
}

Error fields

id (string): A stable, uppercase identifier. Use this field to identify and handle specific errors programmatically.
message (string): Human-readable details about the error. May contain dynamic information about the specific failure. This field is usually present but may occasionally be missing.
code (number): DEPRECATED - Legacy numeric error code maintained for backward compatibility. Will be removed in future versions.

Note: When using Portal SDK, the raw response structure may not be directly exposed to your application, but you can still access the id and message fields through the SDK’s error handling mechanisms.

Error identifier format

Error identifiers follow a consistent naming pattern:

MODULE_[CONTEXT_]ERROR

MODULE: The system component where the error originated (e.g., AUTH, RPC, WS)
CONTEXT: Optional qualifier providing additional context
ERROR: The specific error condition

Examples:

AUTH_FAILED - Authentication failure
MSG_BUILD_FAILED - Failed to build the message
DKG_FAILED - Distributed Key Generation failed

Example of errors in different categories

General errors

These errors can occur across various MPC operations:

Error ID	Description
`ERROR`	Generic error when a more specific error type isn’t available
`INTERNAL_ERROR`	Internal server error - typically indicates an unexpected system issue
`BAD_REQUEST`	Invalid request format or parameters
`NOT_FOUND`	Requested resource not found
`STATE_INVALID`	Operation attempted in an invalid state
`OPERATION_IN_PROGRESS`	Another operation is already in progress
`WEBHOOK_FAILED`	Webhook verification or execution failed

Authentication & access control

Errors related to authentication, authorization and security:

Error ID	Description
`AUTH_FAILED`	Authentication failed - invalid credentials or token
`ADDRESS_BLOCKED`	The address is blocked from performing this operation
`POLICY_AMOUNT_LIMIT_EXCEEDED`	A policy blocked the transaction for exceeding a configured amount limit

Transaction & message building

Errors that occur when constructing, signing, and sending transactions and messages:

Error ID	Description
`TX_BUILD_FAILED`	Failed to build the transaction
`MSG_BUILD_FAILED`	Failed to build the message
`METHOD_UNSUPPORTED`	The requested method is not supported
`RPC_OP_FAILED`	RPC operation failed (often includes details like insufficient funds)
`MPC_PROTOCOL_UNSUPPORTED`	The requested MPC protocol is not supported

WebSocket communication

Network and WebSocket-specific errors:

Error ID	Description
`WS_MSG_MALFORMED`	WebSocket message format is invalid
`WS_NETWORK_ERROR`	Network error during WebSocket communication
`WS_CLOSED`	WebSocket connection was unexpectedly closed
`WS_READ_FAILED`	Failed to read from WebSocket
`WS_WRITE_FAILED`	Failed to write to WebSocket

MPC protocol operations

Errors specific to Multi-Party Computation operations:

Error ID	Description
`DKG_FAILED`	Distributed Key Generation failed
`DKG_REFRESH_FAILED`	DKG refresh operation failed
`DKG_REFRESH_MISMATCH`	DKG refresh data mismatch detected
`SIGN_FAILED`	Signature generation failed
`SIGN_SHARE_MISMATCH`	Share mismatch detected when signing
`ENCRYPT_FAILED`	Encryption operation failed
`DECRYPT_FAILED`	Decryption operation failed

Errors related to cryptographic keys and share operations:

Error ID	Description
`SAVE_SIGNING_SHARE_FAILED`	Failed to save signing share
`SAVE_BACKUP_SHARE_FAILED`	Failed to save backup share
`PUBLIC_KEY_BUILD_FAILED`	Failed to build public key
`PUBLIC_KEY_VERIFICATION_FAILED`	Public key verification failed
`ADDRESS_CALC_FAILED`	Wallet address calculation failed
`PRIVATE_KEY_RECOVERY_FAILED`	Private key recovery operation failed
`SHARE_PARSING_FAILED`	Failed to parse provided share
`METADATA_INVALID`	Invalid metadata provided

Error handling guidelines

1. Use error IDs for logic

Always use the id field when implementing error handling logic. Error IDs are stable and designed for programmatic use.

2. Optional human-readable messages

Use the message field to get details about the error. Depending on your use case, the message can be displayed to users or included as additional context in application error logs. Avoid parsing the message content programmatically, as the wording may change over time.

3. Avoid using numeric codes

Do not use the deprecated code field. It exists only for backward compatibility and will be removed in future versions.

4. Handle missing messages

While rare, the message field may occasionally be missing. Always provide a fallback when displaying errors to users.

Common error resolution

When encountering persistent errors that cannot be resolved through standard error handling:

Check Portal Status: Visit the Portal status page to check for any ongoing service disruptions or maintenance.
Verify Input Data: Ensure all input parameters are correctly formatted and valid:
- Cipher text hasn’t been modified or corrupted
- Addresses are properly formatted
- Transaction parameters are within acceptable ranges
Contact Support: If the issue persists, contact Portal support with:
- The error ID
- The complete error message
- Steps to reproduce the issue
- Any relevant request/response data (excluding sensitive information)

Migration Guide

If you’re migrating from the old numeric error system to the new string-based identifiers:

Old system (numeric codes)

Previously, errors were identified by numeric codes in ranges:

1xx: MPC Errors
2xx: Network Errors
3xx: General Errors
4xx: Encryption Errors
5xx: Portal Connect Errors

New system (string IDs)

Now, use specific string identifiers:

// Old system - checking specific numeric codes
if (error.code === 101) {
  // Handle DKG failure
}
if (error.code === 201) {
  // Handle network error
}

// New system - checking specific string IDs
if (error.id === 'DKG_FAILED') {
  // Handle DKG failure
}
if (error.id === 'WS_NETWORK_ERROR' || ) {
  // Handle network error
}

The string-based system provides more meaningful error identification without needing to remember numeric ranges or codes.

Additional resources

Portal Status Page

Getting Started

SDKs

APIs

Integrations

Resources

Error structure

Error fields

Error identifier format

Example of errors in different categories

General errors

Authentication & access control

Transaction & message building

WebSocket communication

MPC protocol operations

Error handling guidelines

1. Use error IDs for logic

2. Optional human-readable messages

3. Avoid using numeric codes

4. Handle missing messages

Common error resolution

Migration Guide

Old system (numeric codes)

New system (string IDs)

Additional resources

​Error structure

​Error fields

​Error identifier format

​Example of errors in different categories

​General errors

​Authentication & access control

​Transaction & message building

​WebSocket communication

​MPC protocol operations

​Key & share management

​Error handling guidelines

​1. Use error IDs for logic

​2. Optional human-readable messages

​3. Avoid using numeric codes

​4. Handle missing messages

​Common error resolution

​Migration Guide

​Old system (numeric codes)

​New system (string IDs)

​Additional resources

Error structure

Error fields

Error identifier format

Example of errors in different categories

General errors

Authentication & access control

Transaction & message building

WebSocket communication

MPC protocol operations

Key & share management

Error handling guidelines

1. Use error IDs for logic

2. Optional human-readable messages

3. Avoid using numeric codes

4. Handle missing messages

Common error resolution

Migration Guide

Old system (numeric codes)

New system (string IDs)

Additional resources