Error Handling
Understand and resolve common errors, HTTP codes, and troubleshooting for smooth V3 Custody operations.
{
"status": "success",
"data": {
"transactionId": "tx_123abc",
"status": "pending"
}
}
{
"status": "error",
"code": "BAD_REQUEST",
"message": "Invalid request parameters"
}
{
"status": "error",
"code": "UNAUTHORIZED",
"message": "Invalid or missing API key"
}
{
"status": "error",
"code": "FORBIDDEN",
"message": "Insufficient permissions for this action"
}
{
"status": "error",
"code": "TOO_MANY_REQUESTS",
"message": "Rate limit exceeded. Retry after 60s"
}
{
"status": "error",
"code": "INTERNAL_SERVER_ERROR",
"message": "Temporary service issue. Retry later"
}
HTTP Status Codes
V3 Custody API returns standard HTTP status codes to indicate the outcome of your requests. Review these responses to diagnose issues quickly.
Always check the code field in error responses for specific guidance. Include it when contacting support.
Common Error Categories
Use these tabs to troubleshoot specific error types in V3 Custody.
MPC signing errors occur during multi-party computation for secure transaction signing.
Verify Key Shares
Ensure all signer key shares are online and synced. Check the dashboard at https://dashboard.example.com/signers.
Retry Signing
curl -X POST https://api.example.com/v1/transactions/sign \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{"transactionId": "tx_123abc"}'
Check Logs
Review signer logs for MPC_TIMEOUT or KEY_SHARE_MISMATCH.
The policy engine enforces rules like limits and approvals before signing.
Common Violations
| Violation Code | Description | Resolution |
|---|---|---|
LIMIT_EXCEEDED | Transfer exceeds daily limit | Request approval or adjust policy |
UNAPPROVED | Missing multi-sig approval | Add required signers |
INVALID_RECIPIENT | Recipient not whitelisted | Update policy whitelist |
Policy identifier from your configuration.
Blockchain-specific issues like invalid gas or nonce errors.
// Ethereum: Insufficient gas
{
code: "INSUFFICIENT_GAS",
message: "Increase gas limit to 21000+"
}
// Bitcoin: Invalid UTXO
{
code: "UTXO_NOT_FOUND",
message: "Select valid unspent outputs"
}
Retry with corrected parameters.
General Troubleshooting Workflow
Follow these steps for any error in V3 Custody.
Capture Full Response
Log the complete API response including headers.
Enable Debug Mode
Set debug: true in your API client config.
Reproduce Minimally
Isolate the request to minimal payload.
Contact Support
Provide error code, timestamp, and request ID.
Logging and Debug Techniques
Capture detailed logs to diagnose issues.
const response = await fetch('https://api.example.com/v1/transactions', {
headers: { 'Authorization': `Bearer ${YOUR_API_KEY}` }
});
if (!response.ok) {
const error = await response.json();
console.error(`Error ${response.status}:`, error);
}
curl -v -X GET https://api.example.com/v1/balances \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "X-Debug: true"
Quick Resolutions
Check API Key
Verify YOUR_API_KEY validity and permissions.
Review Policies
Update limits and approvals in policy engine.
Signer Health
Monitor MPC signer uptime on dashboard.
Rate Limits
Implement exponential backoff for 429 errors.
For persistent issues, export logs from https://dashboard.example.com/logs and share with support@v3.finance.