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 → Task is truncated-and-completed, deleted, or cancelled, and its keyspace range is re-dispatched. The job is not failed. See Task Lifecycle and Statuses
8. Hashcat execution error → Agent-reported task failure (failed), which fails the whole job

Cloud Provisioning Errors¶

Cloud errors divide into two classes, and the distinction decides whether money is at stake. A definitive failure means no instance exists; an ambiguous one means an instance may be running and billing right now.

1. Configuration — refused before anything is spent
2. No VPN provider configured → refused. "the backend is not internet-exposed, so an instance that cannot join your VPN would bill until its watchdog fired"
3. Unsupported VPN provider → refused, naming OpenVPN's /dev/net/tun / CAP_NET_ADMIN requirement
4. Missing credentials, VPN credential, or backend_vpn_host → provider cannot be enabled
5. Expired reusable VPN key → "the reusable <provider> key expired at <time>; rotate it before provisioning"

6. Peer provider without acknowledgement → refused at provider level and again per client

7. Provisioning refusals — no spend, diagnostic recorded on the job

8. cloud_rental_too_short — the rental would be mostly commissioning. Two distinct messages depending on whether the client's TTL ceiling or their remaining budget is binding, because telling someone to top up a budget when their own ceiling is the problem sends them to the wrong screen
9. Budget reached, instance cap reached, outside the provisioning window, below the minimum job priority → skip reasons shown on the job detail page

10. Unfunded client → cannot provision at all, distinct from being at 100% of budget

11. Launch outcomes

12. ErrOfferUnavailable — definitive. The provider refused for capacity (InsufficientInstanceCapacity). The budget reservation is released and the claim voucher deactivated, and the retry loop moves to the next candidate
13. VcpuLimitExceeded / MaxSpotInstanceCountExceeded — account quotas that will never clear without a limit-increase request, unlike a capacity refusal
14. UnauthorizedOperation (bare, no detail) → a RunInstances ARN type is missing from the IAM policy. See AWS IAM

15. Anything else — ambiguous. The instance row is left for the reaper to reconcile by label, the reservation is not released, and the claim voucher is deliberately left active because the instance may be running and its agent still has to register

16. Teardown

17. DELETE /instances/{id} returning 502 → the provider refused the destroy. The instance is still billing. It keeps accruing and keeps blocking new provisioning for its client until resolved
18. Repeated teardown failure → admins are paged with the raw provider ID; the instance is never reported terminated, because that would hide real spend

19. AGENT_DISK_FULL on a cloud agent → treated as structural, not transient. The instance is terminated rather than retried into a loop that burns its whole TTL, because container-provider disk cannot grow after creation

20. Capacity explorer (GET /providers/{id}/capacity)

21. 502 — the provider was reachable but the probe failed. Unlike pre-flight, this is a real error: without the placement list there is no screen to render
22. 501 — the provider chooses placement itself and has no axis to select. Today only mock

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