{"id":244,"date":"2026-05-17T13:00:37","date_gmt":"2026-05-17T13:00:37","guid":{"rendered":"https:\/\/abrarqasim.com\/blog\/axum-error-handling-split-that-stopped-opaque-500s\/"},"modified":"2026-05-17T13:00:37","modified_gmt":"2026-05-17T13:00:37","slug":"axum-error-handling-split-that-stopped-opaque-500s","status":"publish","type":"post","link":"https:\/\/abrarqasim.com\/blog\/axum-error-handling-split-that-stopped-opaque-500s\/","title":{"rendered":"Axum Error Handling: the Split That Stopped My Opaque 500s"},"content":{"rendered":"

I shipped a small Axum service last month, a webhook receiver for some Stripe events, and the first thing I had to wrestle with again was error handling. Not because Axum makes it hard. Because Rust gives you about four reasonable shapes for an error type, and a vocal opinion online for every one of them.<\/p>\n

Here’s what I landed on after the third iteration. It’s not novel. It’s the split that finally felt sane: thiserror<\/code> for the errors my code can actually branch on, anyhow<\/code> for the “this is a bug or an outage” errors, and a thin IntoResponse<\/code> impl that turns either one into a real HTTP response without leaking my internals to the caller.<\/p>\n

If you’ve been writing Axum handlers and you keep slapping anyhow::Result<\/code> on every function, then squinting at the 500 in your logs trying to figure out which step failed, this post is for you.<\/p>\n

Why anyhow on its own falls over inside Axum handlers<\/h2>\n

I started the service the lazy way. Every handler returned anyhow::Result<Json<T>><\/code> and I added a single From<anyhow::Error><\/code> impl that turned everything into a 500 with a generic body.<\/p>\n

async fn create_subscription(\n    State(db): State<PgPool>,\n    Json(input): Json<NewSub>,\n) -> anyhow::Result<Json<Subscription>> {\n    let row = sqlx::query_as!(...).fetch_one(&db).await?;\n    Ok(Json(row.into()))\n}\n<\/code><\/pre>\n
That worked for about a week. Then I caught myself returning 500 when a customer sent a malformed UUID in the path, 500 when a Stripe ID was already used, and 500 when our Postgres connection pool tripped. Three different failures, same status code, same opaque message. I couldn’t even write a useful integration test for the duplicate case, because my own handler couldn’t tell the difference between a 409 and a service outage.<\/p>\n
The Axum docs are pretty direct about this. The error-handling guide<\/a> tells you to implement IntoResponse<\/code> on your own error type. Once I read that for the third time, I gave in and did the work.<\/p>\n
The split I keep landing on<\/h2>\n
The mental model is small. An error is either “the caller did something I can describe to them” (validation failed, not found, unauthorized) or “something inside the service broke and the caller can’t help” (DB down, third-party API timed out, my own code panicked).<\/p>\n
The first kind wants a specific variant, a stable status code, and a stable response shape. That’s what thiserror<\/code> is for. The second kind is just “anything that went wrong” and the caller doesn’t need detail. That’s what anyhow<\/code> is for.<\/p>\n
use thiserror::Error;\n\n#[derive(Debug, Error)]\npub enum AppError {\n    #[error("not found")]\n    NotFound,\n    #[error("conflict: {0}")]\n    Conflict(String),\n    #[error("invalid input: {0}")]\n    BadRequest(String),\n    #[error("unauthorized")]\n    Unauthorized,\n    #[error(transparent)]\n    Internal(#[from] anyhow::Error),\n}\n<\/code><\/pre>\n
The #[error(transparent)]<\/code> plus #[from] anyhow::Error<\/code> is the bit that makes this play nicely with ?<\/code>. I can still write .context(\"loading subscription\")?<\/code> on a sqlx<\/code> call and the error rolls up into AppError::Internal<\/code> without me writing any glue. Anything I want the caller to know about, I match on and return a specific variant.<\/p>\n
I covered some of this when I wrote about Axum patterns that actually stuck<\/a>, but the error angle is the one I keep tweaking.<\/p>\n
Making IntoResponse do the boring work<\/h2>\n
The conversion from AppError<\/code> to an HTTP response is where most teams I’ve seen get cute. Don’t. Keep it boring.<\/p>\n
use axum::{\n    http::StatusCode,\n    response::{IntoResponse, Response},\n    Json,\n};\nuse serde_json::json;\n\nimpl IntoResponse for AppError {\n    fn into_response(self) -> Response {\n        let (status, code, message) = match &self {\n            AppError::NotFound => (\n                StatusCode::NOT_FOUND,\n                "not_found",\n                "resource not found".to_string(),\n            ),\n            AppError::Conflict(m) => (StatusCode::CONFLICT, "conflict", m.clone()),\n            AppError::BadRequest(m) => (StatusCode::BAD_REQUEST, "bad_request", m.clone()),\n            AppError::Unauthorized => (\n                StatusCode::UNAUTHORIZED,\n                "unauthorized",\n                "auth required".to_string(),\n            ),\n            AppError::Internal(err) => {\n                tracing::error!(error = ?err, "internal error");\n                (\n                    StatusCode::INTERNAL_SERVER_ERROR,\n                    "internal",\n                    "something went wrong".to_string(),\n                )\n            }\n        };\n\n        (status, Json(json!({ "code": code, "message": message }))).into_response()\n    }\n}\n<\/code><\/pre>\n
A few things I do on purpose here. The internal variant logs the full error chain with ?err<\/code>, so I get the anyhow<\/code> context in my logs, but the response body never sees it. Every variant returns the same envelope, { code, message }<\/code>, so the frontend has exactly one parser to write. Status codes get picked once at the type level, not at every call site.<\/p>\n
Once this is wired up, every handler can go back to being small:<\/p>\n
async fn get_subscription(\n    State(db): State<PgPool>,\n    Path(id): Path<Uuid>,\n) -> Result<Json<Subscription>, AppError> {\n    let row = sqlx::query_as!(Subscription, "select ... where id = $1", id)\n        .fetch_optional(&db)\n        .await\n        .context("loading subscription")?\n        .ok_or(AppError::NotFound)?;\n    Ok(Json(row))\n}\n<\/code><\/pre>\n
The .context()<\/code> call attaches a label that ends up in the log line for Internal<\/code> errors. The .ok_or(AppError::NotFound)?<\/code> turns a missing row into a real 404 with the right body shape. I do not have to think about HTTP at this layer.<\/p>\n
Logging without leaking internals to the client<\/h2>\n
One thing I had to remind myself: 4xx errors are messages to the caller, 5xx errors are messages to me. So I log them differently.<\/p>\n
For AppError::Internal<\/code>, I emit tracing::error!<\/code> with the full chain. The response body stays vague on purpose. For 4xx variants, I log at debug<\/code>, or I skip the log entirely. They’re not bugs, they’re conversation.<\/p>\n
I learned this the hard way when our log volume tripled overnight, because I had tracing::warn!<\/code> on every BadRequest<\/code>. Anyone bored could spam our API and fill the logs. I dropped the broad warns and only logged what was actually surprising.<\/p>\n
The anyhow docs<\/a> on .context()<\/code> are worth a re-read here. The point isn’t that anyhow gives you fancier errors. It’s that anyhow makes building a useful chain trivial. I attach context at every layer that might be ambiguous later: “loading subscription”, “decoding Stripe payload”. Future-me reading the log at 2 a.m. only has to read the chain top to bottom.<\/p>\n
When I reach for AppError vs just punting<\/h2>\n
I have a smaller side project, a CLI that hits a couple of REST APIs, where the whole error type is just anyhow::Result<\/code>. No AppError<\/code>. No IntoResponse<\/code>. The CLI prints the error chain and exits. That’s correct. The shape above only earns its keep when there’s a contract with a caller that cares about status codes and stable bodies.<\/p>\n
A rough rule I use:<\/p>\n