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

***


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.1moneynetwork.com/integrations/rest-apis/error-codes.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.