Error Codes
REST API Error Codes
This document provides a comprehensive reference for all error codes returned by the 1Money Network REST API. Each error includes a structured error code, HTTP status code, description, and example response.
Error Response Format
All API errors follow a consistent JSON response format:
{
"error_code": "validation_invalid_address",
"message": "Invalid address format: 0xinvalid"
}
Error Categories
400 Bad Request - Client Input Validation Errors
These errors indicate that the client request contains invalid or malformed data.
validation_invalid_address
HTTP Status: 400 Bad Request
Description: The provided address format is invalid
Example: Invalid Ethereum address format
Response:
{
"error_code": "validation_invalid_address",
"message": "Invalid address format: 0xinvalid"
}
validation_invalid_hash
HTTP Status: 400 Bad Request
Description: The provided hash format is invalid
Example: Invalid transaction hash or block hash format
Response:
{
"error_code": "validation_invalid_hash",
"message": "Invalid hash format: 0xinvalidhash"
}
validation_invalid_param
HTTP Status: 400 Bad Request
Description: A parameter value is invalid or malformed
Example: Invalid numeric value, enum value, or parameter format
Response:
{
"error_code": "validation_invalid_param",
"message": "Invalid parameter 'amount': must be a positive number"
}
validation_missing_param
HTTP Status: 400 Bad Request
Description: A required parameter is missing from the request
Example: Missing required field in request body or query parameters
Response:
{
"error_code": "validation_missing_param",
"message": "Missing required parameter: recipient"
}
validation_query_error
HTTP Status: 400 Bad Request
Description: Query parameters are malformed or invalid
Example: Invalid query string format or unsupported parameters
Response:
{
"error_code": "validation_query_error",
"message": "Invalid query parameters: unsupported parameter 'invalid_param'"
}
validation_invalid_signature
HTTP Status: 400 Bad Request
Description: Transaction signature is invalid or malformed
Example: Invalid cryptographic signature format
Response:
{
"error_code": "validation_invalid_signature",
"message": "Invalid signature: signature verification failed"
}
validation_invalid_transaction
HTTP Status: 400 Bad Request
Description: Transaction structure or format is invalid
Example: Malformed transaction data or invalid transaction type
Response:
{
"error_code": "validation_invalid_transaction",
"message": "Invalid transaction: missing required field 'nonce'"
}
404 Not Found - Resource Not Found Errors
These errors indicate that the requested resource does not exist.
resource_checkpoint_not_found
HTTP Status: 404 Not Found
Description: The requested checkpoint does not exist
Example: Checkpoint with specified ID or hash not found
Response:
{
"error_code": "resource_checkpoint_not_found",
"message": "Checkpoint not found: 12345"
}
resource_transaction_not_found
HTTP Status: 404 Not Found
Description: The requested transaction does not exist
Example: Transaction with specified hash not found
Response:
{
"error_code": "resource_transaction_not_found",
"message": "Transaction not found: 0xabcd1234..."
}
resource_account_not_found
HTTP Status: 404 Not Found
Description: The requested account does not exist
Example: Account with specified address not found
Response:
{
"error_code": "resource_account_not_found",
"message": "Account not found: 0x1234567890abcdef..."
}
resource_token_not_found
HTTP Status: 404 Not Found
Description: The requested token does not exist
Example: Token with specified address not found
Response:
{
"error_code": "resource_token_not_found",
"message": "Token not found: 0xtoken123..."
}
resource_epoch_not_found
HTTP Status: 404 Not Found
Description: The requested epoch does not exist
Example: Epoch with specified ID not found
Response:
{
"error_code": "resource_epoch_not_found",
"message": "Epoch not found: 42"
}
422 Unprocessable Entity - Business Logic Errors
These errors indicate that the request is well-formed but cannot be processed due to business rule violations.
business_transaction_failed
HTTP Status: 422 Unprocessable Entity
Description: Transaction processing failed due to business rules
Example: Transaction validation failed, insufficient gas, or other business logic errors
Response:
{
"error_code": "business_transaction_failed",
"message": "Transaction processing failed: insufficient gas for execution"
}
business_insufficient_balance
HTTP Status: 422 Unprocessable Entity
Description: Account has insufficient balance for the operation
Example: Attempting to transfer more tokens than available
Response:
{
"error_code": "business_insufficient_balance",
"message": "Insufficient balance: required 1000, available 500"
}
business_authority_failed
HTTP Status: 422 Unprocessable Entity
Description: Authority validation failed for the operation
Example: Insufficient permissions for token operations or governance actions
Response:
{
"error_code": "business_authority_failed",
"message": "Authority validation failed: insufficient permissions for mint operation"
}
business_token_operation_failed
HTTP Status: 422 Unprocessable Entity
Description: Token operation cannot be performed
Example: Token is paused, blacklisted account, or other token-specific restrictions
Response:
{
"error_code": "business_token_operation_failed",
"message": "Token operation not allowed: token is currently paused"
}
500 Internal Server Error - System Errors
These errors indicate internal system problems that are not caused by client input.
system_database_error
HTTP Status: 500 Internal Server Error
Description: Database or storage system error
Example: Database connection failure, storage corruption, or query execution error
Response:
{
"error_code": "system_database_error",
"message": "Database error: connection timeout"
}
system_network_error
HTTP Status: 500 Internal Server Error
Description: Network or communication error
Example: P2P network issues, consensus communication failures
Response:
{
"error_code": "system_network_error",
"message": "Network error: failed to connect to peer nodes"
}
system_service_error
HTTP Status: 500 Internal Server Error
Description: Internal service error
Example: Consensus service failure, execution engine error, or other internal component errors
Response:
{
"error_code": "system_service_error",
"message": "Internal service error: consensus - checkpoint processing failed"
}
system_config_error
HTTP Status: 500 Internal Server Error
Description: System configuration error
Example: Invalid configuration, missing required settings, or configuration conflicts
Response:
{
"error_code": "system_config_error",
"message": "Configuration error: missing required validator configuration"
}
408 Request Timeout - Request Processing Timeout
This error indicates that the server timed out while processing the request.
request_timeout
HTTP Status: 408 Request Timeout
Description: The server timed out while processing the request (10 second timeout)
Example: Long-running operations that exceed the server timeout limit
Response:
{
"error_code": "request_timeout",
"message": "Request timeout: processing time exceeded 10 seconds"
}
WebSocket Specific Errors
These errors are specific to WebSocket connections and real-time subscriptions.
websocket_invalid_message
HTTP Status: 400 Bad Request
Description: Invalid WebSocket subscription message
Example: Malformed subscription request or unsupported message format
Response:
{
"error_code": "websocket_invalid_message",
"message": "Invalid subscription message: unsupported subscription type"
}
websocket_unsupported_codec
HTTP Status: 400 Bad Request
Description: Unsupported WebSocket codec
Example: Client requested unsupported message encoding format
Response:
{
"error_code": "websocket_unsupported_codec",
"message": "Unsupported WebSocket codec: binary"
}
Error Handling Best Practices
For API Clients
Always check the
error_code
field for programmatic error handlingUse the HTTP status code to determine the general error category
Display the
message
field to users for human-readable error descriptions
For Application Developers
Implement retry logic for 5xx system errors and 408 timeout errors
Validate input on the client side to minimize 4xx validation errors
Handle 404 errors gracefully by showing appropriate "not found" messages
For 422 errors, guide users to correct business logic violations
For 408 timeout errors, implement exponential backoff retry strategies
Monitor error rates and patterns for system health insights
Common Error Scenarios
Transaction Submission
validation_invalid_transaction
: Malformed transaction datavalidation_invalid_signature
: Invalid cryptographic signaturebusiness_transaction_failed
: Transaction rejected by business rulesbusiness_insufficient_balance
: Not enough funds for the operation
Resource Queries
validation_invalid_address
: Invalid address format in queryvalidation_invalid_hash
: Invalid hash format in queryresource_transaction_not_found
: Transaction doesn't existresource_account_not_found
: Account doesn't exist
Token Operations
resource_token_not_found
: Token doesn't existbusiness_authority_failed
: Insufficient permissionsbusiness_token_operation_failed
: Token-specific restrictions
System Issues
system_database_error
: Storage system problemssystem_service_error
: Internal component failuressystem_network_error
: Network connectivity issues
Timeout Issues
request_timeout
: Server processing timeout (10 second limit exceeded)
Last updated