Error Handling in Web Handlers

21 min read

In Express.js, an error usually means an try/catch that calls res.status(500).json(...), or a thrown error that lands in a four-argument error middleware. Axum takes a different route: a handler simply returns Result<T, AppError>, and you teach the framework — once — how to turn AppError into an HTTP response. This chapter builds a production-grade error type with thiserror, wires it to Axum’s IntoResponse trait, and maps every error variant to the right status code.

Quick Overview

In a Rust web app you do not throw exceptions and you do not pepper handlers with try/catch. Instead you define one application error type (an enum), implement the IntoResponse trait for it so Axum knows the status code and JSON body to send, and let the ? operator propagate failures out of handlers automatically. The payoff is that error handling becomes part of the type system: a handler’s signature tells you exactly what can go wrong, and you cannot forget to handle an error path because the compiler will not let you.

The current stable toolchain is Rust 1.96.0 on the latest stable edition (2024); cargo new selects it automatically. This page targets axum 0.8, thiserror 2, and anyhow 1.

TypeScript/JavaScript Example

Here is the way most Express APIs handle errors: a custom error class carrying a status code, try/catch in async handlers, and a centralized error-handling middleware as a backstop.

1
// errors.ts — a custom error class with an HTTP status
2
export class ApiError extends Error {
3
  constructor(
4
    public status: number,
5
    message: string,
6
    public code: string,
7
  ) {
8
    super(message);
9
    this.name = "ApiError";
10
  }
11

12
  static notFound(what: string) {
13
    return new ApiError(404, `${what} was not found`, "not_found");
14
  }
15

16
  static validation(message: string) {
17
    return new ApiError(422, message, "validation");
18
  }
19

20
  static unauthorized() {
21
    return new ApiError(401, "you are not authorized to do that", "unauthorized");
22
  }
23
}

1
// app.ts — handlers throw, middleware catches
2
import express, { Request, Response, NextFunction } from "express";
3
import { ApiError } from "./errors";
4

5
const app = express();
6
app.use(express.json());
7

8
const users = new Map<number, string>([[1, "Alice"]]);
9

10
app.get("/users/:id", (req: Request, res: Response, next: NextFunction) => {
11
  try {
12
    const id = Number(req.params.id);
13
    const name = users.get(id);
14
    if (name === undefined) {
15
      throw ApiError.notFound(`user ${id}`); // jumps to the error middleware
16
    }
17
    res.json({ id, name });
18
  } catch (err) {
19
    next(err); // hand off to the centralized handler
20
  }
21
});
22

23
// Centralized error-handling middleware: MUST have 4 args, registered LAST.
24
app.use((err: unknown, _req: Request, res: Response, _next: NextFunction) => {
25
  if (err instanceof ApiError) {
26
    res.status(err.status).json({ error: err.message, code: err.code });
27
  } else {
28
    console.error("unhandled error:", err); // log the real thing
29
    res.status(500).json({ error: "internal server error" }); // hide details
30
  }
31
});
32

33
app.listen(3000);

Key points and pain points:

Every async handler needs try/catch + next(err), or a thrown error silently hangs the request (in classic Express without express-async-errors).
The error middleware is identified only by its arity (four parameters). Forget one and Express treats it as a normal middleware — a notorious footgun.
Nothing in a handler’s type signature tells you which errors it can produce; you discover them at runtime.
It is easy to accidentally leak an internal error’s message to the client.

Rust Equivalent

Axum’s model: a handler returns Result<T, AppError>, the ? operator replaces try/catch, and one impl IntoResponse for AppError replaces the error middleware. Set up the dependencies first:

1
cargo new my-api
2
cd my-api
3
cargo add axum@0.8
4
cargo add tokio@1 --features full
5
cargo add serde --features derive
6
cargo add serde_json
7
cargo add thiserror@2
8
cargo add tracing

1
// src/main.rs — the same API in Axum, with a typed error
2
use axum::{
3
    extract::{Path, State},
4
    http::StatusCode,
5
    response::{IntoResponse, Response},
6
    routing::get,
7
    Json, Router,
8
};
9
use serde::Serialize;
10
use serde_json::json;
11
use std::{collections::HashMap, sync::Arc};
12
use tokio::sync::RwLock;
13

14
// The application's single error type. `thiserror` derives `Display` + `Error`
15
// from the `#[error("...")]` messages, so we never hand-write a match for them.
16
#[derive(Debug, thiserror::Error)]
17
enum AppError {
18
    #[error("user {0} was not found")]
19
    NotFound(u64),
20

21
    #[error("invalid input: {0}")]
22
    Validation(String),
23

24
    #[error("you are not authorized to do that")]
25
    Unauthorized,
26

27
    // `#[from]` lets `?` turn a serde_json::Error into AppError automatically.
28
    #[error("failed to (de)serialize JSON")]
29
    Json(#[from] serde_json::Error),
30

31
    // A catch-all for unexpected failures. We never leak the inner message.
32
    #[error("internal server error")]
33
    Internal(#[source] Box<dyn std::error::Error + Send + Sync>),
34
}
35

36
// The shape every error sends back to the client.
37
#[derive(Serialize)]
38
struct ErrorBody {
39
    error: String,
40
}
41

42
// THIS is the bridge: it teaches Axum how to turn an AppError into an HTTP
43
// response. Each variant chooses its own status code.
44
impl IntoResponse for AppError {
45
    fn into_response(self) -> Response {
46
        let status = match &self {
47
            AppError::NotFound(_) => StatusCode::NOT_FOUND,
48
            AppError::Validation(_) => StatusCode::UNPROCESSABLE_ENTITY,
49
            AppError::Unauthorized => StatusCode::UNAUTHORIZED,
50
            AppError::Json(_) => StatusCode::BAD_REQUEST,
51
            AppError::Internal(_) => StatusCode::INTERNAL_SERVER_ERROR,
52
        };
53

54
        // Log the *full* error server-side (5xx especially), but only send a
55
        // safe, public message to the client.
56
        if status.is_server_error() {
57
            tracing::error!(error = ?self, "request failed");
58
        }
59

60
        let body = Json(ErrorBody {
61
            error: self.to_string(),
62
        });
63
        (status, body).into_response()
64
    }
65
}
66

67
type Db = Arc<RwLock<HashMap<u64, String>>>;
68

69
// Handlers return `Result<T, AppError>`. `T: IntoResponse` for the success arm,
70
// `AppError: IntoResponse` for the failure arm — Axum responds to either.
71
async fn get_user(
72
    State(db): State<Db>,
73
    Path(id): Path<u64>,
74
) -> Result<Json<serde_json::Value>, AppError> {
75
    let users = db.read().await;
76
    let name = users.get(&id).ok_or(AppError::NotFound(id))?;
77
    Ok(Json(json!({ "id": id, "name": name })))
78
}
79

80
async fn risky(Path(n): Path<i64>) -> Result<String, AppError> {
81
    if n < 0 {
82
        return Err(AppError::Validation("n must be >= 0".into()));
83
    }
84
    // `?` converts serde_json::Error into AppError::Json via the `#[from]` impl.
85
    let parsed: i64 = serde_json::from_str("not a number")?;
86
    Ok(parsed.to_string())
87
}
88

89
async fn secret() -> Result<String, AppError> {
90
    Err(AppError::Unauthorized)
91
}
92

93
#[tokio::main]
94
async fn main() {
95
    let db: Db = Arc::new(RwLock::new(HashMap::from([(1, "Alice".to_string())])));
96

97
    let app = Router::new()
98
        .route("/users/{id}", get(get_user))
99
        .route("/risky/{n}", get(risky))
100
        .route("/secret", get(secret))
101
        .with_state(db);
102

103
    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
104
    axum::serve(listener, app).await.unwrap();
105
}

Running this server and hitting each route produces the following real responses (captured with curl -w "\nHTTP %{http_code}\n"):

1
$ curl -s http://127.0.0.1:3000/users/1
2
{"id":1,"name":"Alice"}            # HTTP 200
3

4
$ curl -s http://127.0.0.1:3000/users/99
5
{"error":"user 99 was not found"}  # HTTP 404
6

7
$ curl -s http://127.0.0.1:3000/risky/-5
8
{"error":"invalid input: n must be >= 0"}   # HTTP 422
9

10
$ curl -s http://127.0.0.1:3000/risky/5
11
{"error":"failed to (de)serialize JSON"}    # HTTP 400
12

13
$ curl -s http://127.0.0.1:3000/secret
14
{"error":"you are not authorized to do that"}   # HTTP 401

One enum, one IntoResponse impl, and every handler stays clean. There is no error middleware to register in the right order, and no way to forget the error path: if get_user did not handle the missing-user case, the ? on ok_or(...) simply would not type-check.

Detailed Explanation

`thiserror` derives the boilerplate

thiserror is the idiomatic crate for library/application error enums. The #[derive(thiserror::Error)] macro reads each variant’s #[error("...")] attribute and generates:

an impl std::fmt::Display whose output is the formatted message, and
an impl std::error::Error (including source() when you mark an inner field with #[source] or #[from]).

The message strings support inline field interpolation: #[error("user {0} was not found")] pulls in the tuple field .0, just like format!("user {0}", self.0). This is why self.to_string() in into_response produces the message you saw in the JSON. You write the message once; thiserror wires up Display, Error, and source() for free. It is not a decorator — it is a compile-time code generator that expands into plain trait impls.

Note: thiserror adds zero runtime cost and no dependency at runtime — it is a proc-macro that runs at compile time and disappears. Contrast this with extending an Error class in JavaScript, which is an ordinary runtime object.

`IntoResponse` is the contract

Axum can only respond with types that implement the IntoResponse trait. Many types already do: String, &str, StatusCode, Json<T>, and tuples like (StatusCode, Json<T>). By implementing it for AppError, you make your error a first-class response. The match &self chooses a status code per variant; the success and failure arms of a handler’s Result are both converted through IntoResponse, which is why Result<Json<...>, AppError> works as a return type.

Tip: The (StatusCode, Json<T>) tuple is the workhorse here. Returning (StatusCode::NOT_FOUND, Json(body)).into_response() sets the status line and a JSON body in one expression. See Request and Response for the full set of IntoResponse implementations.

`?` replaces `try/catch`

The ? operator is the engine of Rust error handling. When you write users.get(&id).ok_or(AppError::NotFound(id))?, the ? says “if this is Err/None, return that error from the function now.” Because serde_json::Error has a #[from] conversion into AppError::Json, the line serde_json::from_str("not a number")? automatically wraps the underlying error. This is the moral equivalent of throw, but it is explicit, local, and visible in the type signature — you can see at the function boundary exactly what error a handler may emit. See Section 08: Error Handling for the ? operator and the From-based conversion mechanics in depth.

Logging vs. leaking

The branch if status.is_server_error() logs the full Debug representation of the error (including the #[source] chain) with tracing::error!, but the client only ever receives self.to_string() — the public Display message. For 5xx errors we deliberately send the generic "internal server error" so we never leak a database connection string or a stack-trace-like detail to the outside world. This mirrors the console.error(err) + res.status(500).json({error:"internal server error"}) split in the Express example, but here it is enforced by which field each variant exposes.

Key Differences

Concern	Express.js	Axum / Rust
Signaling failure	`throw` an exception	`return Err(...)` / the `?` operator
Error transport	thrown value bubbles up the call stack	`Result<T, E>` returned through the stack
Central handling	4-arg error middleware, registered last	one `impl IntoResponse for AppError`
Status mapping	`err.status` field read at runtime	`match` on the variant, checked at compile time
”What can fail here?“	invisible until runtime	visible in the function’s return type
Forgetting an error path	silently 500s / hangs	does not compile
Leaking internals	easy (`err.message` to client)	explicit: choose which field is public
Cost of the machinery	exception unwinding	a tagged-union return value (no unwinding)

The deepest difference: in TypeScript, error handling is a runtime convention you can forget. In Rust, it is a type-system obligation. A function that returns Result<T, AppError> cannot be used without acknowledging the Err case, so a whole class of “forgot to handle that” bugs disappears.

Note: Unlike a thrown JavaScript exception that unwinds an arbitrary number of frames, ? returns from exactly one function — the one it appears in. Errors travel up one Result-returning call at a time. This is more verbose than throw, but it is also why the control flow is obvious from the signatures.

Common Pitfalls

Pitfall 1: Returning an error type that is not `IntoResponse`

A handler may only return types Axum knows how to respond with. If your error does not implement IntoResponse, the handler is not a valid Handler and you get a confusing trait-bound error rather than a friendly “implement IntoResponse” message.

1
use axum::{routing::get, Router};
2

3
// does not compile (error[E0277]): ParseIntError is not IntoResponse,
4
// so this fn does not satisfy the `Handler` trait.
5
async fn handler() -> Result<String, std::num::ParseIntError> {
6
    let n: i32 = "x".parse()?;
7
    Ok(n.to_string())
8
}
9

10
fn main() {
11
    let _app: Router = Router::new().route("/", get(handler));
12
}

The real error from cargo check (axum 0.8.9, Rust 1.96.0) is:

1
error[E0277]: the trait bound `fn() -> impl Future<Output = Result<String, ParseIntError>> {handler}: Handler<_, _>` is not satisfied
2
   --> src/bin/pitfall.rs:11:53
3
    |
4
 11 |     let _app: Router = Router::new().route("/", get(handler));
5
    |                                                 --- ^^^^^^^ the trait `Handler<_, _>` is not implemented for fn item ...
6
    |                                                 |
7
    |                                                 required by a bound introduced by this call
8
    |
9
    = note: Consider using `#[axum::debug_handler]` to improve the error message
10
note: required by a bound in `axum::routing::get`

Tip: When you see “the trait Handler<_, _> is not implemented”, add #[axum::debug_handler] above the handler (it requires the macros feature) and recompile. It rewrites the error to point at the exact parameter or return type that is the problem. The fix here is to map ParseIntError into your AppError (give AppError a #[from] ParseIntError variant) so the handler returns Result<String, AppError>.

Pitfall 2: Using `unwrap()`/`expect()` instead of returning an error

1
async fn get_user(id: u64) -> String {
2
    let users = std::collections::HashMap::<u64, String>::new();
3
    users.get(&id).unwrap().clone() // panics if the user is missing
4
}

unwrap() on a missing key panics, which Axum/Tower catches and turns into a bare 500 with no body — and crashes that task. Always return Err(AppError::NotFound(id)) via ? instead. Reserve unwrap()/expect() for setup code (like TcpListener::bind(...).await.unwrap() in main) where a failure genuinely means the program cannot start.

Pitfall 3: Forgetting that built-in extractor rejections are not your error type

Axum’s own extractors (Path, Query, Json) reject malformed input before your handler runs, and they reply with their own plain-text error — not your JSON shape. Requesting /users/abc against the example (where the route is /users/{id} with Path<u64>) returns this real response:

1
$ curl -s http://127.0.0.1:3000/users/abc
2
Invalid URL: Cannot parse `abc` to a `u64`       # HTTP 400, plain text

That is a PathRejection, not AppError::NotFound, so it does not go through your IntoResponse. If you want a consistent JSON error envelope across both your domain errors and extractor failures, wrap the extractor — see the Real-World example below.

Pitfall 4: Leaking internal details in 5xx responses

1
// Anti-pattern: sends the raw error (maybe a DB DSN!) to the client.
2
AppError::Internal(e) => (StatusCode::INTERNAL_SERVER_ERROR, e.to_string()),

Send a generic message to the client and log the detail server-side, as the working example does. This is a security practice, not just a style preference — internal error strings frequently contain file paths, SQL, or connection details.

Best Practices

One error type per crate/service. A single AppError enum that every handler returns keeps the response format uniform. Add a variant when you discover a new failure mode.
thiserror for typed enums; anyhow for the catch-all. Use thiserror when callers need to match on specific variants (the typical web-handler case). Use anyhow (or an anyhow-wrapping variant) for the “anything unexpected becomes a 500” path. The two compose well — see Exercise 3.
Map status codes in the match, not at the throw site. Keep the variant-to-status mapping in one into_response so it is easy to audit.
Always log 5xx with the full source chain, return a generic message. tracing::error!(error = ?self, ...) records the Debug (with source()), while the client gets Display.
Use #[from] to make ? ergonomic. Mark the most common foreign errors (serde_json::Error, your DB driver’s error, std::io::Error) with #[from] so handlers can ? them directly.
Initialize a tracing subscriber so those error! logs actually appear. Add cargo add tracing-subscriber --features env-filter and call tracing_subscriber::fmt::init(); at the top of main. See Middleware and Layers for TraceLayer, which logs every request/response automatically.
Pick semantically correct status codes. 400 Bad Request for syntactically malformed input, 422 Unprocessable Entity for well-formed-but-invalid input, 404 for missing resources, 401/403 for auth, 409 for conflicts. The Validation chapter covers returning helpful 400/422 bodies.

Real-World Example

A production API wants every error — whether a domain error you raised or a malformed-JSON rejection from the Json extractor — to come back in the same JSON envelope. The clean way to do this in axum 0.8 is a custom extractor built with #[derive(FromRequest)] that reuses Json but routes its rejection through your AppError. This needs the macros feature:

1
cargo add axum@0.8 --features macros
2
cargo add thiserror@2 serde --features serde/derive
3
cargo add serde_json

1
// src/main.rs — a uniform JSON error envelope for domain + extractor errors
2
use axum::{
3
    extract::{rejection::JsonRejection, FromRequest},
4
    response::{IntoResponse, Response},
5
    routing::post,
6
    Json, Router,
7
};
8
use serde::{Deserialize, Serialize};
9
use serde_json::json;
10

11
#[derive(Debug, thiserror::Error)]
12
enum AppError {
13
    // `#[from]` pulls in axum's own JsonRejection so we can reuse its status code.
14
    #[error("invalid request body: {0}")]
15
    Body(#[from] JsonRejection),
16
}
17

18
impl IntoResponse for AppError {
19
    fn into_response(self) -> Response {
20
        // axum's JsonRejection already knows the right code (400 vs 422 vs 415).
21
        let status = match &self {
22
            AppError::Body(rejection) => rejection.status(),
23
        };
24
        (status, Json(json!({ "error": self.to_string() }))).into_response()
25
    }
26
}
27

28
// A custom extractor: behaves exactly like `Json<T>`, but its rejection is OUR
29
// AppError, so malformed bodies come back in the same envelope as domain errors.
30
#[derive(FromRequest)]
31
#[from_request(via(Json), rejection(AppError))]
32
struct AppJson<T>(T);
33

34
#[derive(Deserialize, Serialize)]
35
struct NewUser {
36
    name: String,
37
}
38

39
async fn create(AppJson(user): AppJson<NewUser>) -> Json<NewUser> {
40
    // In a real handler you would persist `user`; here we echo it back.
41
    Json(user)
42
}
43

44
#[tokio::main]
45
async fn main() {
46
    let app: Router = Router::new().route("/users", post(create));
47
    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
48
    axum::serve(listener, app).await.unwrap();
49
}

Hitting /users with various bodies gives these real responses — notice the status codes are chosen by axum’s JsonRejection::status(), and the body shape is always ours:

1
$ curl -s -X POST /users -H 'content-type: application/json' -d '{"name":"Alice"}'
2
{"name":"Alice"}                                                         # HTTP 200
3

4
$ curl -s -X POST /users -H 'content-type: application/json' -d '{}'
5
{"error":"invalid request body: Failed to deserialize the JSON body into the target type: missing field `name` at line 1 column 2"}
6
                                                                          # HTTP 422
7

8
$ curl -s -X POST /users -H 'content-type: application/json' -d '{not json'
9
{"error":"invalid request body: Failed to parse the request body as JSON: key must be a string at line 1 column 2"}
10
                                                                          # HTTP 400
11

12
$ curl -s -X POST /users -d '{"name":"Alice"}'
13
{"error":"invalid request body: Expected request with `Content-Type: application/json`"}
14
                                                                          # HTTP 415

Now malformed input (400/422/415) and your domain errors share one error format, and the status codes are still semantically correct: 422 for a well-formed JSON object missing a field, 400 for syntactically broken JSON, 415 for a missing/wrong Content-Type. To add domain errors (a NotFound, a Conflict) you just add variants to AppError and extend the match in into_response. The JSON APIs and Validation chapters build full CRUD resources on top of this pattern, and Extractors explains the FromRequest/FromRequestParts machinery behind #[derive(FromRequest)].

Exercises

Exercise 1: A `code` field and a new status

Difficulty: Easy

Objective: Extend an AppError with a machine-readable code field and a 429 Too Many Requests variant.

Instructions:

Define an AppError enum with NotFound, RateLimited, and Internal variants using thiserror.
Implement IntoResponse so each variant returns the right status (404, 429, 500) and a JSON body of the form { "error": "...", "code": "..." }.
The code should be a short stable string like "rate_limited".

Solution

1
use axum::{
2
    http::StatusCode,
3
    response::{IntoResponse, Response},
4
    routing::get,
5
    Json, Router,
6
};
7
use serde_json::json;
8

9
#[derive(Debug, thiserror::Error)]
10
enum AppError {
11
    #[error("resource not found")]
12
    NotFound,
13
    #[error("rate limit exceeded, retry later")]
14
    RateLimited,
15
    #[error("internal server error")]
16
    Internal,
17
}
18

19
impl AppError {
20
    fn status(&self) -> StatusCode {
21
        match self {
22
            AppError::NotFound => StatusCode::NOT_FOUND,
23
            AppError::RateLimited => StatusCode::TOO_MANY_REQUESTS,
24
            AppError::Internal => StatusCode::INTERNAL_SERVER_ERROR,
25
        }
26
    }
27
}
28

29
impl IntoResponse for AppError {
30
    fn into_response(self) -> Response {
31
        let status = self.status();
32
        let code = match self {
33
            AppError::NotFound => "not_found",
34
            AppError::RateLimited => "rate_limited",
35
            AppError::Internal => "internal",
36
        };
37
        (status, Json(json!({ "error": self.to_string(), "code": code }))).into_response()
38
    }
39
}
40

41
async fn h() -> Result<String, AppError> {
42
    Err(AppError::RateLimited)
43
}
44

45
#[tokio::main]
46
async fn main() {
47
    let app: Router = Router::new().route("/", get(h));
48
    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
49
    axum::serve(listener, app).await.unwrap();
50
}

GET / returns {"error":"rate limit exceeded, retry later","code":"rate_limited"} with HTTP 429.

Exercise 2: Convert a foreign error with `#[from]`

Difficulty: Medium

Objective: Let a handler use ? directly on str::parse, converting ParseIntError into your AppError, and add a second validation step.

Instructions:

Give AppError a Parse(#[from] ParseIntError) variant (status 400) and an OutOfRange variant (status 422).
Write a function that parses a string to an integer with ?, then checks it fits in a u8, returning OutOfRange otherwise.
Confirm the ? conversion compiles without an explicit .map_err.

Solution

1
use axum::{
2
    http::StatusCode,
3
    response::{IntoResponse, Response},
4
    routing::get,
5
    Json, Router,
6
};
7
use serde_json::json;
8
use std::num::ParseIntError;
9

10
#[derive(Debug, thiserror::Error)]
11
enum AppError {
12
    #[error("bad number: {0}")]
13
    Parse(#[from] ParseIntError),
14
    #[error("value out of range")]
15
    OutOfRange,
16
}
17

18
impl IntoResponse for AppError {
19
    fn into_response(self) -> Response {
20
        let status = match &self {
21
            AppError::Parse(_) => StatusCode::BAD_REQUEST,
22
            AppError::OutOfRange => StatusCode::UNPROCESSABLE_ENTITY,
23
        };
24
        (status, Json(json!({ "error": self.to_string() }))).into_response()
25
    }
26
}
27

28
async fn parse_and_check(input: &str) -> Result<u8, AppError> {
29
    let n: i64 = input.parse()?; // ParseIntError -> AppError::Parse via `?`
30
    u8::try_from(n).map_err(|_| AppError::OutOfRange)
31
}
32

33
async fn h() -> Result<String, AppError> {
34
    let n = parse_and_check("300").await?; // 300 doesn't fit in a u8
35
    Ok(n.to_string())
36
}
37

38
#[tokio::main]
39
async fn main() {
40
    let app: Router = Router::new().route("/", get(h));
41
    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
42
    axum::serve(listener, app).await.unwrap();
43
}

parse_and_check("abc") would yield 400 {"error":"bad number: invalid digit found in string"}, while "300" yields 422 {"error":"value out of range"}. The ? on input.parse() needs no .map_err because of the #[from] impl.

Exercise 3: Typed variants plus an `anyhow` catch-all

Difficulty: Hard

Objective: Build an AppError that has explicit domain variants and a transparent anyhow catch-all, so unmodeled failures become 500s without you enumerating them — while never leaking the internal message.

Instructions:

Add anyhow (cargo add anyhow).
Define AppError with NotFound(u64), Forbidden, and Unexpected(#[from] anyhow::Error) (use #[error(transparent)] on the catch-all).
In IntoResponse, map domain variants to 404/403, and the catch-all to 500 — but send the generic "internal server error" message for the 500, while logging the real error with tracing::error!.
Show a function that returns Err(anyhow::anyhow!("...").into()) and confirm it surfaces as a 500.

Solution

1
use axum::{
2
    http::StatusCode,
3
    response::{IntoResponse, Response},
4
    routing::get,
5
    Json, Router,
6
};
7
use serde::Serialize;
8
use serde_json::json;
9

10
#[derive(Debug, thiserror::Error)]
11
enum AppError {
12
    #[error("user {0} not found")]
13
    NotFound(u64),
14
    #[error("forbidden")]
15
    Forbidden,
16
    // Catch-all: any error that isn't a known domain case becomes a 500.
17
    #[error(transparent)]
18
    Unexpected(#[from] anyhow::Error),
19
}
20

21
#[derive(Serialize)]
22
struct ErrorBody {
23
    error: String,
24
    kind: &'static str,
25
}
26

27
impl IntoResponse for AppError {
28
    fn into_response(self) -> Response {
29
        let (status, kind) = match &self {
30
            AppError::NotFound(_) => (StatusCode::NOT_FOUND, "not_found"),
31
            AppError::Forbidden => (StatusCode::FORBIDDEN, "forbidden"),
32
            AppError::Unexpected(_) => (StatusCode::INTERNAL_SERVER_ERROR, "internal"),
33
        };
34

35
        // Public message: hide the inner detail for 5xx, expose it otherwise.
36
        let public_message = match &self {
37
            AppError::Unexpected(_) => "internal server error".to_string(),
38
            other => other.to_string(),
39
        };
40

41
        if status.is_server_error() {
42
            tracing::error!(error = ?self, "request failed");
43
        }
44

45
        (status, Json(ErrorBody { error: public_message, kind })).into_response()
46
    }
47
}
48

49
fn lookup(id: u64) -> Result<String, AppError> {
50
    if id == 0 {
51
        // A deep failure we never modeled: bubbles up as anyhow -> 500.
52
        return Err(anyhow::anyhow!("db connection reset").into());
53
    }
54
    if id == 42 {
55
        return Err(AppError::Forbidden);
56
    }
57
    Ok(format!("user-{id}"))
58
}
59

60
async fn h() -> Result<String, AppError> {
61
    let name = lookup(0)?; // triggers the anyhow catch-all
62
    Ok(name)
63
}
64

65
#[tokio::main]
66
async fn main() {
67
    tracing_subscriber::fmt::init(); // needs `cargo add tracing-subscriber`
68
    let app: Router = Router::new().route("/", get(h));
69
    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
70
    axum::serve(listener, app).await.unwrap();
71
}

GET / returns {"error":"internal server error","kind":"internal"} with HTTP 500, while the server log records the real db connection reset cause via tracing::error!. Notice #[error(transparent)] means AppError::Unexpected’s Display forwards to the inner anyhow::Error, but into_response deliberately overrides that for the public 5xx message — typed domain errors and an open-ended catch-all coexist in one enum.

Error Handling in Web Handlers

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

Detailed Explanation

`thiserror` derives the boilerplate

`IntoResponse` is the contract

`?` replaces `try/catch`

Logging vs. leaking

Key Differences

Common Pitfalls

Pitfall 1: Returning an error type that is not `IntoResponse`

Pitfall 2: Using `unwrap()`/`expect()` instead of returning an error

Pitfall 3: Forgetting that built-in extractor rejections are not your error type

Pitfall 4: Leaking internal details in 5xx responses

Best Practices

Real-World Example

Further Reading

Official Documentation

Exercises

Exercise 1: A `code` field and a new status

Exercise 2: Convert a foreign error with `#[from]`

Exercise 3: Typed variants plus an `anyhow` catch-all

Error Handling in Web Handlers

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

Detailed Explanation

thiserror derives the boilerplate

IntoResponse is the contract

? replaces try/catch

Logging vs. leaking

Key Differences

Common Pitfalls

Pitfall 1: Returning an error type that is not IntoResponse

Pitfall 2: Using unwrap()/expect() instead of returning an error

Pitfall 3: Forgetting that built-in extractor rejections are not your error type

Pitfall 4: Leaking internal details in 5xx responses

Best Practices

Real-World Example

Further Reading

Official Documentation

Related Topics

Exercises

Exercise 1: A code field and a new status

Exercise 2: Convert a foreign error with #[from]

Exercise 3: Typed variants plus an anyhow catch-all

`thiserror` derives the boilerplate

`IntoResponse` is the contract

`?` replaces `try/catch`

Pitfall 1: Returning an error type that is not `IntoResponse`

Pitfall 2: Using `unwrap()`/`expect()` instead of returning an error

Exercise 1: A `code` field and a new status

Exercise 2: Convert a foreign error with `#[from]`

Exercise 3: Typed variants plus an `anyhow` catch-all