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 IDDescription
ERRORGeneric error when a more specific error type isn’t available
INTERNAL_ERRORInternal server error - typically indicates an unexpected system issue
BAD_REQUESTInvalid request format or parameters
NOT_FOUNDRequested resource not found
STATE_INVALIDOperation attempted in an invalid state
OPERATION_IN_PROGRESSAnother operation is already in progress
WEBHOOK_FAILEDWebhook verification or execution failed

​
Authentication & access control

Errors related to authentication, authorization and security:
Error IDDescription
AUTH_FAILEDAuthentication failed - invalid credentials or token
ADDRESS_BLOCKEDThe address is blocked from performing this operation

​
Transaction & message building

Errors that occur when constructing, signing, and sending transactions and messages:
Error IDDescription
TX_BUILD_FAILEDFailed to build the transaction
MSG_BUILD_FAILEDFailed to build the message
METHOD_UNSUPPORTEDThe requested method is not supported
RPC_OP_FAILEDRPC operation failed (often includes details like insufficient funds)
MPC_PROTOCOL_UNSUPPORTEDThe requested MPC protocol is not supported

​
WebSocket communication

Network and WebSocket-specific errors:
Error IDDescription
WS_MSG_MALFORMEDWebSocket message format is invalid
WS_NETWORK_ERRORNetwork error during WebSocket communication
WS_CLOSEDWebSocket connection was unexpectedly closed
WS_READ_FAILEDFailed to read from WebSocket
WS_WRITE_FAILEDFailed to write to WebSocket

​
MPC protocol operations

Errors specific to Multi-Party Computation operations:
Error IDDescription
DKG_FAILEDDistributed Key Generation failed
DKG_REFRESH_FAILEDDKG refresh operation failed
DKG_REFRESH_MISMATCHDKG refresh data mismatch detected
SIGN_FAILEDSignature generation failed
SIGN_SHARE_MISMATCHShare mismatch detected when signing
ENCRYPT_FAILEDEncryption operation failed
DECRYPT_FAILEDDecryption operation failed

​
Key & share management

Errors related to cryptographic keys and share operations:
Error IDDescription
SAVE_SIGNING_SHARE_FAILEDFailed to save signing share
SAVE_BACKUP_SHARE_FAILEDFailed to save backup share
PUBLIC_KEY_BUILD_FAILEDFailed to build public key
PUBLIC_KEY_VERIFICATION_FAILEDPublic key verification failed
ADDRESS_CALC_FAILEDWallet address calculation failed
PRIVATE_KEY_RECOVERY_FAILEDPrivate key recovery operation failed
SHARE_PARSING_FAILEDFailed to parse provided share
METADATA_INVALIDInvalid 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:
  1. Check Portal Status: Visit the Portal status page to check for any ongoing service disruptions or maintenance.
  2. 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
  3. 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