KrakenHashes Error Codes Reference¶

This document provides a comprehensive reference for all error codes, HTTP status codes, and error conditions used throughout the KrakenHashes system.

Table of Contents¶

• HTTP Status Codes
• Application Error Types
• Agent Error Conditions
• WebSocket Error Messages
• Common Error Scenarios

HTTP Status Codes¶

The KrakenHashes API uses standard HTTP status codes to indicate the success or failure of requests.

Success Codes (2xx)¶

Client Error Codes (4xx)¶

Server Error Codes (5xx)¶

Application Error Types¶

Model Layer Errors (backend/internal/models/errors.go)¶

var (
    ErrNotFound     = errors.New("record not found")
    ErrInvalidInput = errors.New("invalid input")
)

Repository Layer Errors (backend/internal/repository/errors.go)¶

var (
    // Resource Errors
    ErrNotFound         = errors.New("resource not found")
    ErrDuplicateRecord  = errors.New("duplicate record")

    // Validation Errors
    ErrInvalidStatus    = errors.New("invalid status")
    ErrInvalidToken     = errors.New("invalid token")
    ErrInvalidHardware  = errors.New("invalid hardware information")
    ErrInvalidMetrics   = errors.New("invalid metrics")

    // Voucher Errors
    ErrInvalidVoucher      = errors.New("invalid or expired voucher")
    ErrVoucherAlreadyUsed  = errors.New("voucher has already been used")
    ErrVoucherDeactivated  = errors.New("voucher has been deactivated")
    ErrVoucherExpired      = errors.New("voucher has expired")

    // Agent Errors
    ErrDuplicateToken  = errors.New("agent token already exists")
    ErrAgentNotFound   = errors.New("agent not found")
)

Agent Error Conditions¶

Registration Errors¶

Authentication Errors¶

Connection Errors¶

WebSocket Error Messages¶

Message Types¶

The WebSocket protocol uses typed messages for communication between agents and the server.

Server to Agent Error Messages¶

{
    "type": "error_report",
    "payload": {
        "error": "error_message",
        "code": "ERROR_CODE",
        "details": {}
    }
}

Agent to Server Error Messages¶

{
    "type": "error_report",
    "payload": {
        "agent_id": 123,
        "error": "error description",
        "stack": "stack trace if available",
        "context": {},
        "reported_at": "2025-01-20T10:30:00Z"
    }
}

WebSocket Message Types¶

Agent → Server Messages¶

Server → Agent Messages¶

Common Error Scenarios¶

Authentication Flow Errors¶

1. Login Failures
2. Invalid credentials → 401 Unauthorized
3. System user login attempt → 401 Unauthorized

4. MFA required but not provided → Response with MFA session

5. Token Errors

6. Expired access token → 401 Unauthorized
7. Invalid refresh token → 401 Unauthorized

8. Expired refresh token → 401 Unauthorized

9. MFA Errors

10. Invalid TOTP code → 400 Bad Request
11. Invalid email code → 400 Bad Request
12. Expired MFA session → 401 Unauthorized
13. Invalid backup code → 400 Bad Request

File Operation Errors¶

1. Upload Errors
2. File too large → 400 Bad Request
3. Invalid file type → 400 Bad Request

4. Disk space exceeded → 507 Insufficient Storage

5. Download Errors

6. File not found → 404 Not Found
7. Access denied → 403 Forbidden

Job Execution Errors¶

1. Job Creation
2. Invalid job parameters → 400 Bad Request
3. Missing required fields → 400 Bad Request

4. Invalid hashlist ID → 404 Not Found

5. Job Execution

6. No available agents → 503 Service Unavailable
7. Agent disconnected → Job marked as failed
8. Hashcat execution error → Job error status

Database Errors¶

1. Connection Errors
2. Database unreachable → 500 Internal Server Error

3. Connection pool exhausted → 500 Internal Server Error

4. Query Errors

5. Record not found → 404 Not Found
6. Duplicate key violation → 409 Conflict
7. Foreign key constraint → 400 Bad Request

Error Resolution Guide¶

For API Consumers¶

1. 401 Unauthorized
2. Check if access token is expired
3. Refresh token if needed

4. Ensure proper authentication headers

5. 403 Forbidden

6. Verify user has required permissions

7. Check role-based access requirements

8. 404 Not Found

9. Verify resource ID is correct

10. Check if resource was deleted

11. 500 Internal Server Error

12. Retry with exponential backoff
13. Check server logs for details
14. Contact support if persistent

For Agent Developers¶

1. WebSocket Connection Issues
2. Ensure TLS is enabled
3. Verify API key is valid

4. Check network connectivity

5. File Sync Errors

6. Verify file permissions
7. Check disk space

8. Ensure file hashes match

9. Job Execution Errors

10. Check hashcat installation
11. Verify GPU drivers
12. Monitor system resources

Error Logging¶

All errors are logged with appropriate severity levels:

• DEBUG: Detailed debugging information
• INFO: General informational messages
• WARNING: Warning messages for potential issues
• ERROR: Error messages for failures
• CRITICAL: Critical system failures

Error logs include: - Timestamp - Error message - Stack trace (when available) - Request context - User/Agent information

Best Practices¶

1. Client-Side Error Handling
2. Always check HTTP status codes
3. Parse error response bodies
4. Implement retry logic for transient errors

5. Display user-friendly error messages

6. Server-Side Error Handling

7. Use consistent error formats
8. Include helpful error details
9. Log errors with appropriate context

10. Monitor error rates and patterns

11. Agent Error Handling

12. Report errors via WebSocket
13. Implement local error recovery
14. Maintain error history
15. Include system state in error reports