Error Handling

By Phase 6 the books API works, but the handlers smell. Every one that can fail spells out its own failure inline: look up a book, and if it's missing, return StatusCode::NOT_FOUND; parse something bad, and build a (StatusCode::BAD_REQUEST, "...") tuple by hand. The happy path and sad path tangle together, and every handler invents its own error shape.

Here's the thing other frameworks make hard and axum makes beautiful: in axum, an error is a return value, not an exception. There's no throw, no exception unwinding the stack, no global error handler you register and hope fires. You make one type that knows how to turn itself into an HTTP response, and your handlers just hand that type back. The language does the rest.

📝 Mental model: a handler returning Result<T, E> is a valid axum handler as long as both T and E implement IntoResponse. You already know IntoResponse from Phase 3. So define your own AppError, implement IntoResponse for it once, and every handler can return Result<_, AppError>. The ? operator propagates failures for you, and axum renders whatever comes back - success or error - through the same machinery.

One error type, one response shape

Start by naming the ways your API can fail. For the books service that's a small set: the book doesn't exist, the client sent something invalid, or something broke on our end. That's an enum.

use axum::{
    Json,
    http::StatusCode,
    response::{IntoResponse, Response},
};

enum AppError {
    NotFound,
    BadRequest(String),
    Internal,
}

impl IntoResponse for AppError {
    fn into_response(self) -> Response {
        let (status, msg) = match self {
            AppError::NotFound => (StatusCode::NOT_FOUND, "not found".to_string()),
            AppError::BadRequest(m) => (StatusCode::BAD_REQUEST, m),
            AppError::Internal => {
                (StatusCode::INTERNAL_SERVER_ERROR, "internal error".to_string())
            }
        };
        (status, Json(serde_json::json!({ "error": msg }))).into_response()
    }
}

What just happened: AppError enumerates the failure modes, with BadRequest(String) carrying a message so callers know what was wrong. The impl IntoResponse is the whole trick - the single place that decides how an error becomes HTTP. We match the variant into a (status, message) pair, then build the response from a tuple: (StatusCode, Json<...>) already implements IntoResponse (Phase 3), so wrapping the message in serde_json::json! gives every error the same JSON envelope - {"error": "..."}. Change that shape here, once, and every endpoint's errors change with it.

Rewriting the handlers with ?

Now the payoff. Compare the Phase 6 style - manual StatusCode returns - with what AppError lets you write. Here's a show handler, before:

// Phase 6 style: failure handling tangled into the handler.
async fn show(
    State(state): State<AppState>,
    Path(id): Path<u32>,
) -> Result<Json<Book>, StatusCode> {
    let books = state.books.lock().unwrap();
    match books.get(&id) {
        Some(book) => Ok(Json(book.clone())),
        None => Err(StatusCode::NOT_FOUND),
    }
}

And after, with AppError and ?:

use axum::extract::{Path, State};

async fn show(
    State(state): State<AppState>,
    Path(id): Path<u32>,
) -> Result<Json<Book>, AppError> {
    let books = state.books.lock().unwrap();
    let book = books.get(&id).cloned().ok_or(AppError::NotFound)?;
    Ok(Json(book))
}

What just happened: the match collapsed into one line. books.get(&id) returns an Option<&Book>; .cloned() turns it into Option<Book>; and .ok_or(AppError::NotFound) converts that into a Result<Book, AppError> - Some becomes Ok, None becomes Err(AppError::NotFound). ? then says "if this is an Err, return it right now; otherwise unwrap the Ok." Because AppError: IntoResponse, that Err is a complete, valid response - axum renders it as our 404 JSON. The handler now reads as the happy path with failure points marked by ?.

Validation gets the same treatment. Suppose creating a book requires a non-empty title:

async fn create(
    State(state): State<AppState>,
    Json(book): Json<Book>,
) -> Result<StatusCode, AppError> {
    if book.title.trim().is_empty() {
        return Err(AppError::BadRequest("title must not be empty".into()));
    }
    state.books.lock().unwrap().insert(book.id, book);
    Ok(StatusCode::CREATED)
}

What just happened: a plain return Err(...) short-circuits with a 400 and our message; the success path returns 201 Created. Both arms are values of the same Result<StatusCode, AppError>, both implement IntoResponse, so axum handles either without you wiring up anything extra. The error is the return value.

Folding foreign errors in with From

The ? operator has a second superpower you haven't used yet: it doesn't just propagate an error, it converts it. When you write something? and the error type doesn't match your function's error type, Rust looks for a From impl to bridge them. That's how you let ? swallow errors from libraries - a database driver, a JSON parser - that know nothing about your AppError.

Say a future version of the books API talks to a real database via sqlx. Its calls return Result<_, sqlx::Error>. Teach AppError how to absorb that:

impl From<sqlx::Error> for AppError {
    fn from(err: sqlx::Error) -> Self {
        match err {
            sqlx::Error::RowNotFound => AppError::NotFound,
            other => {
                tracing::error!("db error: {other}");
                AppError::Internal
            }
        }
    }
}

What just happened: this From<sqlx::Error> impl maps a missing row to our NotFound and treats every other database failure as Internal - logging the real cause with tracing while sending the client only a generic 500. Now a handler can use ? directly on a sqlx call:

async fn show_db(
    State(state): State<AppState>,
    Path(id): Path<u32>,
) -> Result<Json<Book>, AppError> {
    let book = sqlx::query_as::<_, Book>("SELECT * FROM books WHERE id = $1")
        .bind(id)
        .fetch_one(&state.db)
        .await?; // sqlx::Error -> AppError, automatically
    Ok(Json(book))
}

What just happened: fetch_one yields Result<Book, sqlx::Error>, but the function returns Result<_, AppError>. The ? sees the mismatch, finds your From<sqlx::Error> for AppError, and converts on the way out - a RowNotFound becomes a clean 404, anything else a logged 500. One ? does propagation and conversion and the correct status code, with zero boilerplate in the handler.

💡 Writing impl IntoResponse and a pile of From impls by hand gets old. The thiserror crate generates them from a derive: annotate each variant with a #[from] and a display message and it writes the From/Display impls for you, leaving just the IntoResponse. For quick app code that doesn't need a typed enum, anyhow gives you one catch-all error type (anyhow::Error) and an ergonomic ? everywhere. Reach for thiserror when callers need to distinguish variants; reach for anyhow when they don't.

Let the framework handle what it already handles

One trap worth naming: don't reinvent error handling axum already does for you.

⚠️ axum's built-in extractors reject bad input before your handler runs, with sensible defaults. Send a malformed JSON body to a handler taking Json<Book> and you get a 400 Bad Request with a useful message, unwritten by you. Same for a missing path segment, a bad Query, an oversized body. You can customize these rejections, but the defaults are good - only override them when you genuinely need a different shape.

⚠️ And the cardinal rule: don't panic in a handler - return an error. A .unwrap() on a failing Result, an out-of-bounds index, an expect() that fires - these unwind the task instead of producing a tidy response. axum catches it and returns a bare 500, but you've lost the chance to log context, choose a status, or shape the body. Every fallible step should be a ? into your AppError, not a panic. (The one .unwrap() surviving in this guide is state.books.lock().unwrap() - a poisoned Mutex means another thread already panicked holding it, so the process is arguably doomed anyway.)

💡 The shape to keep in your head: extractor rejections guard the door (bad input never reaches you), ? with AppError handles everything your logic can hit, and panics are bugs, not a control-flow tool. Get those three straight and your error handling is both correct and almost invisible.

Recap

• In axum an error is a return value, not an exception: a handler returning Result<T, E> is valid whenever both T and E implement IntoResponse.
• Define one AppError enum and implement IntoResponse for it once so every endpoint shares a single JSON error shape - change it in one place.
• Handlers return Result<_, AppError> and use ? with helpers like .ok_or(AppError::NotFound), collapsing tangled matches into the happy path with marked failure points.
• The ? operator also converts: an impl From<E> for AppError lets ? fold foreign errors (e.g. sqlx::Error) into your type - mapping to the right status and logging the real cause while hiding internals.
• Use thiserror to derive the From/Display boilerplate, or anyhow for a catch-all app error when callers don't need to distinguish variants.
• Lean on axum's built-in extractor rejections for bad input, and never panic in a handler - return an error so you control the status, body, and logs.

Quick check

Lock in the error model before moving on to testing and production.

[
  {
    "q": "What makes a handler returning Result<Json<Book>, AppError> a valid axum handler?",
    "choices": [
      "AppError is registered in a global error handler",
      "Both Json<Book> and AppError implement IntoResponse",
      "The handler is wrapped in a try/catch layer",
      "AppError derives Clone"
    ],
    "answer": 1,
    "explain": "axum accepts any Result handler as long as both the Ok type and the Err type implement IntoResponse - then it renders whichever one is returned."
  },
  {
    "q": "Why does `let b = books.get(&id).cloned().ok_or(AppError::NotFound)?;` work?",
    "choices": [
      "ok_or turns the Option into a Result, and ? returns the Err (an IntoResponse) or unwraps the Ok",
      "? catches a panic raised by get()",
      "ok_or logs the error and returns 200 anyway",
      "It only compiles if AppError implements Clone"
    ],
    "answer": 0,
    "explain": "ok_or maps None to Err(AppError::NotFound); ? then early-returns that Err (which is an IntoResponse, so a complete response) or unwraps the Some."
  },
  {
    "q": "How does `?` let a handler call a sqlx function that returns sqlx::Error and still return AppError?",
    "choices": [
      "sqlx::Error and AppError are the same type",
      "? silently discards the sqlx error and returns Internal",
      "An impl From<sqlx::Error> for AppError lets ? convert the error as it propagates",
      "axum auto-converts any error into AppError"
    ],
    "answer": 2,
    "explain": "When the error types differ, ? looks for a From impl. Implementing From<sqlx::Error> for AppError makes ? convert and propagate in one step."
  }
]