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

  1. Always check the error_code field for programmatic error handling

  2. Use the HTTP status code to determine the general error category

  3. Display the message field to users for human-readable error descriptions

For Application Developers

  1. Implement retry logic for 5xx system errors and 408 timeout errors

  2. Validate input on the client side to minimize 4xx validation errors

  3. Handle 404 errors gracefully by showing appropriate "not found" messages

  4. For 422 errors, guide users to correct business logic violations

  5. For 408 timeout errors, implement exponential backoff retry strategies

  6. 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)


Last updated