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 handling
Use 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 data
validation_invalid_signature: Invalid cryptographic signature
business_transaction_failed: Transaction rejected by business rules
business_insufficient_balance: Not enough funds for the operation

Resource Queries

validation_invalid_address: Invalid address format in query
validation_invalid_hash: Invalid hash format in query
resource_transaction_not_found: Transaction doesn't exist
resource_account_not_found: Account doesn't exist

Token Operations

resource_token_not_found: Token doesn't exist
business_authority_failed: Insufficient permissions
business_token_operation_failed: Token-specific restrictions

System Issues

system_database_error: Storage system problems
system_service_error: Internal component failures
system_network_error: Network connectivity issues

Timeout Issues

request_timeout: Server processing timeout (10 second limit exceeded)

PreviousEstimate fee NextWebsocket

Last updated 26 days ago