# 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:

```json
{
  "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**:

```json
{
  "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**:

```json
{
  "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**:

```json
{
  "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**:

```json
{
  "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**:

```json
{
  "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**:

```json
{
  "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**:

```json
{
  "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**:

```json
{
  "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**:

```json
{
  "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**:

```json
{
  "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**:

```json
{
  "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**:

```json
{
  "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**:

```json
{
  "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**:

```json
{
  "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**:

```json
{
  "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**:

```json
{
  "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**:

```json
{
  "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**:

```json
{
  "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**:

```json
{
  "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**:

```json
{
  "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**:

```json
{
  "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**:

```json
{
  "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**:

```json
{
  "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)

***