Error structure
MPC operations return errors in a standardized JSON format: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 theid
andmessage
fields through the SDK’s error handling mechanisms.
Error identifier format
Error identifiers follow a consistent naming pattern:- MODULE: The system component where the error originated (e.g.,
AUTH
,RPC
,WS
) - CONTEXT: Optional qualifier providing additional context
- ERROR: The specific error condition
AUTH_FAILED
- Authentication failureMSG_BUILD_FAILED
- Failed to build the messageDKG_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 |
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 |
Key & share management
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 theid
field when implementing error handling logic. Error IDs are stable and designed for programmatic use.
2. Optional human-readable messages
Use themessage
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 deprecatedcode
field. It exists only for backward compatibility and will be removed in future versions.
4. Handle missing messages
While rare, themessage
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