Troubleshooting Guide

This guide helps you diagnose and resolve errors encountered when using Institutional Vault. It catalogs MPA (MPC Policy Authority) error codes with their typical HTTP statuses, descriptions, and recommended resolutions.

Overview

Errors in Institutional Vault flow through two layers:

MPA (MPC Policy Authority) layer — The policy/wallet engine returns M-prefixed error codes (e.g., M0001, M0080).
Wallet API (Mothership) — The API maps MPA errors to standard HTTP status codes (e.g., 400, 401, 403, 404, 408, 409, 429, 500, 503).

API error responses may include a correlationId for support troubleshooting. When escalating an issue, always include the correlation ID and the error code from the response.

MPA Error Codes (M-codes)

MPA (MPC Policy Authority) error codes are defined in the policy/wallet engine and returned in API responses as errorCode (M-prefixed). The following table lists all M-codes with their typical HTTP status and resolution guidance.

Timeout and Connectivity

Code	HTTP Status	Description	Resolution
M0001	408 Request Timeout	A timeout waiting for a response from a target service	Retry the operation. If it persists, check network connectivity and MPA node health.
M0002	408	Approval timeout	Operation was not approved within the required timeframe. Retry and ensure approvers complete approval in time.
M0003	503 Service Unavailable	Node not ready	MPA node is not ready to serve requests. Wait and retry; check node startup and configuration.
M0004	503	Critical state	System is in a critical state. Check MPA node logs; contact support if it persists.

Cancellation

Code	HTTP Status	Description	Resolution
M0005	—	Operation cancelled	The operation was cancelled. No action required; retry if needed.

User and Onboarding

Code	HTTP Status	Description	Resolution
M0010	401	User not onboarded	User must complete onboarding (e.g., approver registration) before performing this action.

Policy and Approval

Code	HTTP Status	Description	Resolution
M0020	400 Bad Request	User group has too few members	Policy requires more active owners in the group. Add members or adjust policy.
M0021	400	Initiator required (legacy policy engine)	Legacy policy engine requires an initiator. Set initiator or migrate to new policy engine.
M0022	400	Missing confirmation	Required confirmation was not provided. Ensure all confirmations are submitted.
M0023	—	Confirmation rejected	A confirmation was rejected. Review and resubmit or cancel the operation.
M0024	—	Approval rejected	An approval was rejected. Review and resubmit or cancel the operation.
M0025	—	Blocked by policy	Operation was blocked by policy. Adjust the request or policy configuration.

Asset and Currency

Code	HTTP Status	Description	Resolution
M0030	400	Unsupported currency	The currency or asset is not supported. Use a supported asset.
M0040	400	Unknown engine	The engine type is not recognized. Check asset/chain configuration.

Token Conflicts (ERC20, SPL, Canton)

Code	HTTP Status	Description	Resolution
M0050	409	ERC20 symbol already exists	An ERC20 token with this symbol is already registered. Use a different symbol or the existing token.
M0051	409	SPL token name exists	SPL token name already exists.
M0052	409	SPL token symbol exists	SPL token symbol already exists.
M0053	409	Blockchain network symbol exists	Blockchain network symbol already exists.
M0054	409	Canton token symbol exists	Canton token symbol already exists.
M0060	409	ERC20 address already exists	ERC20 contract address is already registered.
M0061	409	SPL token address exists	SPL token address already exists.
M0070	404 Not Found	ERC20 address does not exist	The ERC20 contract address is not registered. Add the token first.
M0071	404	SPL token address does not exist	SPL token address is not registered. Add the token first.

Transaction Validation

Code	HTTP Status	Description	Resolution
M0080	400	Insufficient funds	Account does not have enough funds for the transfer. Ensure sufficient balance.
M0081	400	Fee	Transaction does not contain a valid fee. Set an appropriate fee.
M0082	400	Validator not active long enough	Validator is not active long enough to exit. Wait and retry.
M0083	400	Replacement transaction underpriced	Replacement transaction must have a higher gas price. Increase fee.
M0084	—	Inputs missing or spent	Transaction inputs are missing or already spent. Refresh and retry.
M0090	400	Validate transaction	Transaction did not match intent. Verify transaction parameters.
M0091	400	Validate max fee	Transaction did not match intent max fee. Adjust max fee.
M0092	400	Validate destination	Destination did not match intent. Verify destination address or account.
M0093	400	Validate amount	Amount did not match intent. Verify transfer amount.

Cold Wallet Batch

Code	HTTP Status	Description	Resolution
M0100	409	Batch in progress	A batch is already in progress. Complete or cancel it before starting another.
M0101	404	Batch not found	The requested batch was not found. Verify batch ID and cold wallet state.
M0102	400	Incorrect batch	Uploaded signed batch does not match the current batch. Re-sign the current batch.
M0103	400	No batch in progress	No batch is currently in progress. Create a batch first.
M0104	—	Pre-signatures exhausted	No more pre-signatures available for external key operations. Generate more pre-signatures.

External Keys

Code	HTTP Status	Description	Resolution
M0110	—	Operation not supported for external keys	This operation is not supported when using external keys. Use a different key type or operation.

Authentication (JWT)

Authentication errors usually result from invalid or expired credentials (e.g., JWT or API key). The approval service may return RFC 7807 ProblemDetails with type set to: invalid-issuer-or-audience, email-not-verified, app-signature-not-valid, token-expired, nonce-not-valid, jwt-signature-not-valid, or token-parse-error.

Code	HTTP Status	Description	Resolution
M0120	401	JWT invalid issuer or audience	Verify IdP issuer and audience in app configuration. Ensure the token is for the correct environment.
M0121	401	JWT email not verified	Verify the user's email in the IdP before allowing access.
M0122	401	JWT invalid app signature	Check app credentials and signing configuration (e.g., client secret, key).
M0123	401	JWT expired	User must sign in again to obtain a new token.
M0124	401	JWT nonce not valid	Retry sign-in; ensure nonce is not reused.
M0125	401	JWT invalid signature	Token may be corrupted or from the wrong issuer. Verify IdP and token source.
M0126	401	JWT token parse	Ensure the request sends a valid JWT in the expected header or parameter.

General steps: (1) Confirm the user is onboarded (e.g., approver registration completed) if the error indicates user not onboarded (M0010). (2) For JWT errors, verify IdP configuration (issuer, audience, signing keys) and that tokens are not expired. (3) Check API key or certificate if using key-based auth; ensure it is valid and not revoked.

Approver

Code	HTTP Status	Description	Resolution
M0130	409	Approver already onboarded	An attempt was made to change the public key for an already onboarded approver.
M0131	400	Operation not pending approvals	Reject/Approve was called for an operation that is not pending approvals or confirmations.

Unknown

Code	HTTP Status	Description	Resolution
M9999	500	Unknown error	Fallback for unclassified errors. Retry; if it persists, contact support with correlation ID.

Data Collection for Support

When escalating an issue to support, providing the following information will help resolve it faster.

1. Log files

Provide logs with context (surrounding lines), not only the error line.
Include debug-level logs when possible. To enable debug logging:
- Wallet: In wallet.yaml, set log_level: 0 (0 = debug, 1 = info, 2 = warn, 3 = error). Default is 1.
- MPA nodes (policy nodes): Set the environment variable DEFAULT_LOG_LEVEL=debug. Valid values: debug, info, warn, error. Log level is read at process start from the environment only (not from the policy node config files).
Collect logs from all relevant components: Wallet API (Mothership), MPA nodes (policy nodes), and any approval or cold-wallet services.
For mobile or approval apps, include logs from those clients if available.

2. Error messages and correlation IDs

Share the full error message and any stack trace from the UI or SDK.
Include the correlation ID from the API response headers. This allows support to correlate with server-side logs.
Note the error code (M-code) and the HTTP status of the response.

3. Configuration

Include configuration details as recorded in logs at startup (sensitive values are typically masked).
Do not share secrets, API keys, or passwords.

4. Context

Frequency and pattern: Does the issue happen every time, at certain times, or randomly?
Affected platforms: Which environments or clients are affected? Which are working?
Reproduction steps: Minimal steps to reproduce the issue.
Customer code: If permitted, share the code or request shape used to call the API or SDK.

Providing this information upfront helps the support team diagnose and resolve issues more quickly.