Error Reference

​

Error Response Format

{
  "success": false,
  "message": "Human-readable error message",
  "code": "ERR_XXX",
  "category": "ERROR_CATEGORY",
  "statusCode": 400,
  "path": "/api/v1/endpoint",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "requestId": "req_123456789"
}

​

Error Fields

• message: User-friendly error message
• code: Unique error code (ERR_XXX format)
• category: Error category (VALIDATION, RESOURCE, CONFLICT, etc.)
• statusCode: HTTP status code
• path: API endpoint where error occurred
• timestamp: When the error occurred
• requestId: Unique request identifier for support

​

Error Categories

• VALIDATION: Input validation errors
• RESOURCE: Resource not found or invalid
• CONFLICT: Resource conflicts (e.g., already exists)
• UNKNOWN_ERROR: General errors
• NETWORK: Network-related errors
• AUTHENTICATION: Authentication/authorization errors

​

General Errors (0-99)

​

ERR_000 - Already Exists

• Attempting to create a resource that already exists

• Check if the resource already exists before creating
• Use update endpoints if modifying existing resources

​

ERR_001 - Profile Already Exists

• Creating a profile with a reference that already exists

• Use a unique reference identifier
• Check existing profiles before creating
• Use the update endpoint if modifying an existing profile

​

ERR_006 - Not Found

• Requesting a resource that doesn’t exist
• Invalid resource ID or reference

• Verify the resource ID or reference is correct
• Check that the resource exists before accessing it
• Ensure you have permission to access the resource

​

ERR_008 - Unauthorized

• Missing or invalid API key
• API key has been revoked or expired

• Verify your API key is correct and included in headers
• Check API key in the dashboard
• Generate a new API key if the current one is invalid
• See Authentication guide for details

​

ERR_009 - Forbidden

• Insufficient permissions for the requested operation
• Resource belongs to a different organization

• Verify you have the necessary permissions
• Check that you’re accessing resources from your organization
• Contact support if permissions seem incorrect

​

ERR_010 - Bad Request

• Invalid request format
• Missing required fields
• Invalid parameter values

• Review the API documentation for required fields
• Validate request parameters before sending
• Check request format matches API specification

​

ERR_014 - Master Wallet Already Generated

• Attempting to generate master wallet shares when they already exist

• Master wallet can only be generated once per organization
• Use existing master wallet shares if already generated

​

ERR_015 - Master Wallet Not Generated

• Attempting to use master wallet before it’s been generated

• Generate master wallet shares first
• Ensure onboarding process is complete

​

ERR_022 - Invalid Pagination

• Invalid skip or take values
• Negative pagination values
• take exceeds maximum allowed (typically 100)

• Use valid pagination values (skip >= 0, take > 0)
• Ensure take doesn’t exceed maximum (100)
• Use default values if not specified

​

Validation Errors (300-399)

​

ERR_302 - Missing Required Field

• Required request field is missing
• Required parameter not provided

• Review API documentation for required fields
• Ensure all required fields are included in request
• Check field names match API specification

​

ERR_303 - Invalid Format

• Field value doesn’t match expected format
• Invalid data type
• Format validation failed (e.g., email, address)

• Verify field format matches API specification
• Check data types are correct
• Validate formats before sending (e.g., valid blockchain address)

​

ERR_304 - Invalid Range

• Numeric value outside allowed range
• Amount exceeds limits

• Check value is within valid range
• Review API documentation for value constraints
• Validate ranges before sending request

​

Contract & Blockchain Errors (100-199)

​

ERR_056 - Contract Template Not Found

• Contract template ID doesn’t exist
• Template was deleted

• Verify contract template ID is correct
• List available templates to find correct ID
• Ensure template hasn’t been deleted

​

ERR_066 - Contract Not Found

• Deployed contract doesn’t exist
• Invalid contract address or deployment ID

• Verify contract address or deployment ID
• Check contract deployment status
• Ensure contract belongs to your organization

​

ERR_068 - Collection Not Found

• Collection ID doesn’t exist
• Collection was deleted

• Verify collection ID is correct
• List available collections to find correct ID
• Check collection deployment status

​

ERR_076 - Contract Function Not Found

• Function name doesn’t exist in contract ABI
• Function signature mismatch

• Verify function name matches contract ABI
• Check function parameters match signature
• Review contract ABI for available functions

​

ERR_096 - Address Not Found

• Address doesn’t exist in system
• Invalid address reference

• Verify address reference is correct
• Ensure address belongs to your organization
• Generate address if it doesn’t exist

​

ERR_126 - Failed Deployment

• Contract deployment transaction failed
• Insufficient gas or network issues
• Invalid contract bytecode

• Check transaction status in workflow
• Verify sufficient balance for gas fees
• Review contract bytecode and constructor parameters
• Check network status

​

ERR_146 - Contract Deployment Not Completed

• Deployment workflow still in progress
• Deployment failed but status not updated

• Check workflow status using Temporal endpoint
• Wait for deployment to complete
• Retry if workflow failed

​

ERR_176 - Invalid Contract Address

• Contract address format is invalid
• Address doesn’t match network format

• Verify address format matches network (Ethereum vs Bitcoin)
• Check address is a valid contract address
• Ensure address is on the correct network

​

ERR_186 - Failed Issue Token

• Token issuance transaction failed
• Collection deployment incomplete
• Network issues

• Check collection deployment status
• Verify workflow completed successfully
• Retry token issuance
• Check network connectivity

​

ERR_196 - Token Not Found

• Token ID doesn’t exist
• Token was burned or removed

• Verify token ID is correct
• Check token exists in collection
• Ensure token hasn’t been burned

​

Network & External Service Errors (200-299)

​

ERR_200 - Network Error

• Connection to blockchain network failed
• Network timeout
• External service unavailable

• Retry the request
• Check network connectivity
• Verify blockchain network status
• Contact support if issue persists

​

ERR_216 - Balance Not Found

• Address has no balance
• Address not indexed yet

• Verify address is correct
• Wait for address indexing to complete
• Check address has received funds

​

ERR_226 - No Unspent Transactions

• Bitcoin address has no UTXOs
• All funds already spent

• Ensure address has received funds
• Wait for transaction confirmation
• Check address balance

​

ERR_236 - Not Enough Balance

• Insufficient funds for transaction
• Balance doesn’t cover amount + fees

• Check available balance
• Ensure balance covers amount and fees
• Account for network fees in calculations

​

Troubleshooting Guide

​

Common Issues

1. Verify API key is correct in dashboard
2. Check API key is included in request headers
3. Ensure no extra spaces in API key
4. Try regenerating API key

1. Verify resource IDs/references are correct
2. Check resource belongs to your organization
3. Ensure resource hasn’t been deleted
4. List resources to find correct identifiers

1. Review API documentation for required fields
2. Check field formats match specification
3. Validate data types are correct
4. Ensure all required fields are provided

1. Check workflow status using Temporal endpoint
2. Wait for async operation to complete
3. Verify workflow completed successfully
4. Retry if workflow failed

​

Getting Help

1. Check Error Details: Review the full error response including code, message, and requestId
2. Review Documentation: Consult relevant guides for your use case
3. Contact Support: Email with:
   • Error code and message
   • Request ID from error response
   • Steps to reproduce
   • Request details (without sensitive data)