Error Handling

⚠️ Error Handling

Levtus provides a structured way to handle errors, both built-in protocol errors and custom application errors.

📡 Built-in Protocol Errors

Levtus automatically handles common HTTP errors during the parsing phase. If any of these occur, the server sends the corresponding status code and closes the connection:

• 400 Bad Request: Malformed request lines, invalid headers, or null byte injections.
• 403 Forbidden: Directory traversal attempts.
• 404 Not Found: Static file not found.
• 408 Request Timeout: Client failed to send data within the timeout period.
• 413 Payload Too Large: Request body or headers exceed configured limits.
• 503 Service Unavailable: Server hit its maximum concurrent connection limit.
• 505 HTTP Version Not Supported: Request used a version other than HTTP/1.0 or HTTP/1.1.

🛠 Custom Error Handling

Using Status Codes

You can manually trigger error responses in your handlers:

app.get("/api/data", ctx -> {
    if (dataMissing()) {
        ctx.status(404).send("Data not found");
        return;
    }
    ctx.json(myData);
});

Catching Exceptions in Middleware

You can wrap next.run() in a try-catch block to create a global error handler:

app.use((ctx, next) -> {
    try {
        next.run();
    } catch (Exception e) {
        System.err.println("Unexpected Error: " + e.getMessage());
        ctx.status(500).send("Internal Server Error");
    }
});

📑 Custom 404 Pages

Since the router is trie-based, you can catch unmatched routes by adding a middleware or a wildcard at the end (future support), or by checking res.isSent() after the router execution.