Refactor error handling

backend/src/api.rs

@@ -31,7 +31,7 @@ use crate::billing::Billing;
 use crate::command::Command;
 use crate::env::Env;
 use crate::infra::Infra;
-use crate::models::Tenant;
+use crate::models::{Relay, Tenant};
 use crate::query::Query;
 use crate::routes::identity::get_identity;
 use crate::routes::invoices::{get_invoice, get_invoice_bolt11, list_tenant_invoices};
@@ -44,7 +44,7 @@ use crate::routes::stripe::{create_stripe_session, stripe_webhook};
 use crate::routes::tenants::{
     create_tenant, get_tenant, list_tenant_relays, list_tenants, update_tenant,
 };
-use crate::web::ApiError;
+use crate::web::{ApiError, forbidden, internal, not_found, unauthorized};
 
 #[derive(Clone)]
 pub struct Api {
@@ -106,7 +106,7 @@ impl Api {
         if self.is_admin(authorized_pubkey) {
             Ok(())
         } else {
-            Err(ApiError::Forbidden("admin required"))
+            Err(forbidden("admin required"))
         }
     }
 
@@ -118,15 +118,23 @@ impl Api {
         if self.is_admin(authorized_pubkey) || authorized_pubkey == tenant_pubkey {
             Ok(())
         } else {
-            Err(ApiError::Forbidden("not authorized"))
+            Err(forbidden("not authorized"))
         }
     }
 
     pub async fn get_tenant_or_404(&self, pubkey: &str) -> Result<Tenant, ApiError> {
         match self.query.get_tenant(pubkey).await {
             Ok(Some(t)) => Ok(t),
-            Ok(None) => Err(ApiError::NotFound("tenant not found")),
+            Ok(None) => Err(not_found("tenant not found")),
-            Err(e) => Err(ApiError::Internal(e.to_string())),
+            Err(e) => Err(internal(e)),
+        }
+    }
+
+    pub async fn get_relay_or_404(&self, id: &str) -> Result<Relay, ApiError> {
+        match self.query.get_relay(id).await {
+            Ok(Some(r)) => Ok(r),
+            Ok(None) => Err(not_found("relay not found")),
+            Err(e) => Err(internal(e)),
         }
     }
 
@@ -137,10 +145,9 @@ impl Api {
     /// This is the intentional session-style variant of NIP-98 used by the
     /// Caravel API: it validates signer identity plus host affinity, and does
     /// not bind to exact request URL/method or maintain replay state. Any
-    /// failure surfaces as `ApiError::Unauthorized`, which renders as 401.
+    /// failure surfaces as a 401 response.
     fn extract_auth_pubkey(&self, headers: &HeaderMap) -> Result<String, ApiError> {
-        self.decode_nip98_pubkey(headers)
+        self.decode_nip98_pubkey(headers).map_err(unauthorized)
-            .map_err(ApiError::Unauthorized)
     }
 
     fn decode_nip98_pubkey(&self, headers: &HeaderMap) -> Result<String> {

backend/src/routes/identity.rs

@@ -1,10 +1,10 @@
 use std::sync::Arc;
 
-use axum::{extract::State, http::StatusCode, response::Response};
+use axum::extract::State;
 use serde::Serialize;
 
 use crate::api::{Api, AuthedPubkey};
-use crate::web::ok;
+use crate::web::{ApiResult, ok};
 
 #[derive(Serialize)]
 struct IdentityResponse {
@@ -15,7 +15,7 @@ struct IdentityResponse {
 pub async fn get_identity(
     State(api): State<Arc<Api>>,
     AuthedPubkey(pubkey): AuthedPubkey,
-) -> Response {
+) -> ApiResult {
     let is_admin = api.is_admin(&pubkey);
-    ok(StatusCode::OK, IdentityResponse { pubkey, is_admin })
+    ok(IdentityResponse { pubkey, is_admin })
 }

backend/src/routes/invoices.rs

@@ -1,42 +1,33 @@
 use std::sync::Arc;
 
-use axum::{
+use axum::extract::{Path, State};
-    extract::{Path, State},
+use reqwest::StatusCode;
-    http::StatusCode,
-    response::Response,
-};
 
 use crate::api::{Api, AuthedPubkey};
 use crate::stripe::InvoiceLookupError;
-use crate::web::{ApiError, err, ok};
+use crate::web::{ApiError, ApiResult, bad_request, internal, not_found, ok};
 
 pub async fn list_tenant_invoices(
     State(api): State<Arc<Api>>,
     AuthedPubkey(auth): AuthedPubkey,
     Path(pubkey): Path<String>,
-) -> Result<Response, ApiError> {
+) -> ApiResult {
     api.require_admin_or_tenant(&auth, &pubkey)?;
     let tenant = api.get_tenant_or_404(&pubkey).await?;
 
-    match api
+    let invoices = api
         .billing
         .stripe_list_invoices(&tenant.stripe_customer_id)
         .await
-    {
+        .map_err(internal)?;
-        Ok(invoices) => Ok(ok(StatusCode::OK, invoices)),
+    ok(invoices)
-        Err(e) => Ok(err(
-            StatusCode::INTERNAL_SERVER_ERROR,
-            "internal",
-            &e.to_string(),
-        )),
-    }
 }
 
 pub async fn get_invoice(
     State(api): State<Arc<Api>>,
     AuthedPubkey(auth): AuthedPubkey,
     Path(id): Path<String>,
-) -> Result<Response, ApiError> {
+) -> ApiResult {
     let (invoice, tenant) = api
         .billing
         .get_invoice_with_tenant(&id)
@@ -50,14 +41,14 @@ pub async fn get_invoice(
         .await
         .map_err(map_invoice_lookup_error)?;
 
-    Ok(ok(StatusCode::OK, invoice))
+    ok(invoice)
 }
 
 pub async fn get_invoice_bolt11(
     State(api): State<Arc<Api>>,
     AuthedPubkey(auth): AuthedPubkey,
     Path(id): Path<String>,
-) -> Result<Response, ApiError> {
+) -> ApiResult {
     let (invoice, tenant) = api
         .billing
         .get_invoice_with_tenant(&id)
@@ -73,46 +64,29 @@ pub async fn get_invoice_bolt11(
 
     let status = invoice["status"].as_str().unwrap_or_default();
     if status != "open" {
-        return Ok(err(
+        return Err(bad_request("invoice-not-open", "invoice is not open"));
-            StatusCode::BAD_REQUEST,
-            "invoice-not-open",
-            "invoice is not open",
-        ));
     }
 
     let amount_due = invoice["amount_due"].as_i64().unwrap_or(0);
     let currency = invoice["currency"].as_str().unwrap_or("usd");
 
-    match api
+    let bolt11 = api
         .billing
         .get_or_create_manual_lightning_bolt11(&id, &tenant.pubkey, amount_due, currency)
         .await
-    {
+        .map_err(internal)?;
-        Ok(bolt11) => Ok(ok(StatusCode::OK, serde_json::json!({ "bolt11": bolt11 }))),
+    ok(serde_json::json!({ "bolt11": bolt11 }))
-        Err(e) => Ok(err(
-            StatusCode::INTERNAL_SERVER_ERROR,
-            "internal",
-            &e.to_string(),
-        )),
-    }
 }
 
 fn map_invoice_lookup_error(error: InvoiceLookupError) -> ApiError {
     match error {
-        InvoiceLookupError::StripeClient { status } => {
+        InvoiceLookupError::StripeClient { status } => match status {
-            let status = StatusCode::from_u16(status.as_u16()).unwrap_or(StatusCode::BAD_REQUEST);
+            StatusCode::NOT_FOUND => not_found("invoice not found"),
-            match status {
+            _ => {
-                StatusCode::NOT_FOUND => ApiError::NotFound("invoice not found"),
+                tracing::warn!(%status, "stripe invoice request returned unexpected status");
-                StatusCode::UNAUTHORIZED | StatusCode::FORBIDDEN => {
+                internal("invoice request rejected")
-                    ApiError::Forbidden("invoice access denied")
-                }
-                _ => ApiError::Client {
-                    status,
-                    code: "invoice-request-rejected",
-                    message: "invoice request rejected",
-                },
             }
-        }
+        },
-        InvoiceLookupError::Internal(error) => ApiError::Internal(error.to_string()),
+        InvoiceLookupError::Internal(error) => internal(error),
     }
 }

backend/src/routes/plans.rs

@@ -1,21 +1,17 @@
 use std::sync::Arc;
 
-use axum::{
+use axum::extract::{Path, State};
-    extract::{Path, State},
-    http::StatusCode,
-    response::Response,
-};
 
 use crate::api::Api;
-use crate::web::{err, ok};
+use crate::web::{ApiResult, not_found, ok};
 
-pub async fn list_plans(State(api): State<Arc<Api>>) -> Response {
+pub async fn list_plans(State(api): State<Arc<Api>>) -> ApiResult {
-    ok(StatusCode::OK, api.query.list_plans())
+    ok(api.query.list_plans())
 }
 
-pub async fn get_plan(State(api): State<Arc<Api>>, Path(id): Path<String>) -> Response {
+pub async fn get_plan(State(api): State<Arc<Api>>, Path(id): Path<String>) -> ApiResult {
     match api.query.get_plan(&id) {
-        Some(plan) => ok(StatusCode::OK, plan),
+        Some(plan) => ok(plan),
-        None => err(StatusCode::NOT_FOUND, "not-found", "plan not found"),
+        None => Err(not_found("plan not found")),
     }
 }

backend/src/routes/relays.rs

@@ -4,8 +4,6 @@ use anyhow::Result;
 use axum::{
     Json,
     extract::{Path, State},
-    http::StatusCode,
-    response::Response,
 };
 use serde::Deserialize;
 
@@ -13,7 +11,10 @@ use crate::api::{Api, AuthedPubkey};
 use crate::models::{
     RELAY_STATUS_ACTIVE, RELAY_STATUS_DELINQUENT, RELAY_STATUS_INACTIVE, Relay,
 };
-use crate::web::{ApiError, err, map_unique_error, ok, parse_bool_default};
+use crate::web::{
+    ApiError, ApiResult, bad_request, created, internal, map_unique_error, ok,
+    parse_bool_default, unprocessable,
+};
 
 #[derive(Deserialize)]
 pub struct CreateRelayRequest {
@@ -51,106 +52,56 @@ pub struct UpdateRelayRequest {
 pub async fn list_relays(
     State(api): State<Arc<Api>>,
     AuthedPubkey(auth): AuthedPubkey,
-) -> Result<Response, ApiError> {
+) -> ApiResult {
     api.require_admin(&auth)?;
 
-    match api.query.list_relays().await {
+    let relays = api.query.list_relays().await.map_err(internal)?;
-        Ok(relays) => Ok(ok(StatusCode::OK, relays)),
+    ok(relays)
-        Err(e) => Err(ApiError::Internal(e.to_string())),
-    }
 }
 
 pub async fn get_relay(
     State(api): State<Arc<Api>>,
     AuthedPubkey(auth): AuthedPubkey,
     Path(id): Path<String>,
-) -> Result<Response, ApiError> {
+) -> ApiResult {
-    let relay = match api.query.get_relay(&id).await {
+    let relay = api.get_relay_or_404(&id).await?;
-        Ok(Some(r)) => r,
-        Ok(None) => return Ok(err(StatusCode::NOT_FOUND, "not-found", "relay not found")),
-        Err(e) => {
-            return Ok(err(
-                StatusCode::INTERNAL_SERVER_ERROR,
-                "internal",
-                &e.to_string(),
-            ));
-        }
-    };
-
     api.require_admin_or_tenant(&auth, &relay.tenant)?;
-
+    ok(relay)
-    Ok(ok(StatusCode::OK, relay))
 }
 
 pub async fn list_relay_activity(
     State(api): State<Arc<Api>>,
     AuthedPubkey(auth): AuthedPubkey,
     Path(id): Path<String>,
-) -> Result<Response, ApiError> {
+) -> ApiResult {
-    let relay = match api.query.get_relay(&id).await {
+    let relay = api.get_relay_or_404(&id).await?;
-        Ok(Some(r)) => r,
-        Ok(None) => return Ok(err(StatusCode::NOT_FOUND, "not-found", "relay not found")),
-        Err(e) => {
-            return Ok(err(
-                StatusCode::INTERNAL_SERVER_ERROR,
-                "internal",
-                &e.to_string(),
-            ));
-        }
-    };
-
     api.require_admin_or_tenant(&auth, &relay.tenant)?;
 
-    match api.query.list_activity_for_relay(&id).await {
+    let activity = api
-        Ok(activity) => Ok(ok(
+        .query
-            StatusCode::OK,
+        .list_activity_for_relay(&id)
-            serde_json::json!({ "activity": activity }),
+        .await
-        )),
+        .map_err(internal)?;
-        Err(e) => Ok(err(
+    ok(serde_json::json!({ "activity": activity }))
-            StatusCode::INTERNAL_SERVER_ERROR,
-            "internal",
-            &e.to_string(),
-        )),
-    }
 }
 
 pub async fn list_relay_members(
     State(api): State<Arc<Api>>,
     AuthedPubkey(auth): AuthedPubkey,
     Path(id): Path<String>,
-) -> Result<Response, ApiError> {
+) -> ApiResult {
-    let relay = match api.query.get_relay(&id).await {
+    let relay = api.get_relay_or_404(&id).await?;
-        Ok(Some(r)) => r,
-        Ok(None) => return Ok(err(StatusCode::NOT_FOUND, "not-found", "relay not found")),
-        Err(e) => {
-            return Ok(err(
-                StatusCode::INTERNAL_SERVER_ERROR,
-                "internal",
-                &e.to_string(),
-            ));
-        }
-    };
-
     api.require_admin_or_tenant(&auth, &relay.tenant)?;
 
-    match fetch_relay_members(&api, &relay).await {
+    let members = fetch_relay_members(&api, &relay).await.map_err(internal)?;
-        Ok(members) => Ok(ok(
+    ok(serde_json::json!({ "members": members }))
-            StatusCode::OK,
-            serde_json::json!({ "members": members }),
-        )),
-        Err(e) => Ok(err(
-            StatusCode::INTERNAL_SERVER_ERROR,
-            "internal",
-            &e.to_string(),
-        )),
-    }
 }
 
 pub async fn create_relay(
     State(api): State<Arc<Api>>,
     AuthedPubkey(auth): AuthedPubkey,
     Json(payload): Json<CreateRelayRequest>,
-) -> Result<Response, ApiError> {
+) -> ApiResult {
     api.require_admin_or_tenant(&auth, &payload.tenant)?;
 
     let relay_id = format!(
@@ -159,7 +110,7 @@ pub async fn create_relay(
         &uuid::Uuid::new_v4().simple().to_string()[..8]
     );
 
-    let mut relay = Relay {
+    let relay = Relay {
         id: relay_id.clone(),
         tenant: payload.tenant,
         schema: relay_id.clone(),
@@ -181,31 +132,13 @@ pub async fn create_relay(
         synced: 0,
     };
 
-    relay = match prepare_relay(&api, relay) {
+    let relay = prepare_relay(&api, relay).map_err(validation_error)?;
-        Ok(r) => r,
-        Err(e) => {
-            return Ok(relay_validation_error_response(e));
-        }
-    };
 
-    match api.command.create_relay(&relay).await {
+    api.command
-        Ok(()) => Ok(ok(StatusCode::CREATED, relay)),
+        .create_relay(&relay)
-        Err(e) => {
+        .await
-            if matches!(map_unique_error(&e), Some("subdomain-exists")) {
+        .map_err(map_relay_write_error)?;
-                Ok(err(
+    created(relay)
-                    StatusCode::UNPROCESSABLE_ENTITY,
-                    "subdomain-exists",
-                    "subdomain already exists",
-                ))
-            } else {
-                Ok(err(
-                    StatusCode::INTERNAL_SERVER_ERROR,
-                    "internal",
-                    &e.to_string(),
-                ))
-            }
-        }
-    }
 }
 
 pub async fn update_relay(
@@ -213,19 +146,8 @@ pub async fn update_relay(
     AuthedPubkey(auth): AuthedPubkey,
     Path(id): Path<String>,
     Json(payload): Json<UpdateRelayRequest>,
-) -> Result<Response, ApiError> {
+) -> ApiResult {
-    let mut relay = match api.query.get_relay(&id).await {
+    let mut relay = api.get_relay_or_404(&id).await?;
-        Ok(Some(r)) => r,
-        Ok(None) => return Ok(err(StatusCode::NOT_FOUND, "not-found", "relay not found")),
-        Err(e) => {
-            return Ok(err(
-                StatusCode::INTERNAL_SERVER_ERROR,
-                "internal",
-                &e.to_string(),
-            ));
-        }
-    };
-
     api.require_admin_or_tenant(&auth, &relay.tenant)?;
 
     let current_plan = relay.plan.clone();
@@ -268,12 +190,7 @@ pub async fn update_relay(
         relay.push_enabled = v;
     }
 
-    relay = match prepare_relay(&api, relay) {
+    let relay = prepare_relay(&api, relay).map_err(validation_error)?;
-        Ok(r) => r,
-        Err(e) => {
-            return Ok(relay_validation_error_response(e));
-        }
-    };
 
     let plan_changed = requested_plan
         .as_deref()
@@ -285,123 +202,61 @@ pub async fn update_relay(
             .get_plan(&relay.plan)
             .expect("validated plan must exist");
         if let Some(limit) = selected_plan.members {
-            let current_members = match fetch_relay_members(&api, &relay).await {
+            let current_members = fetch_relay_members(&api, &relay)
-                Ok(members) => members.len() as i64,
+                .await
-                Err(e) => {
+                .map_err(internal)?
-                    return Ok(err(
+                .len() as i64;
-                        StatusCode::INTERNAL_SERVER_ERROR,
-                        "internal",
-                        &e.to_string(),
-                    ));
-                }
-            };
 
             if current_members > limit {
                 let message = format!(
                     "relay has {current_members} members, which exceeds the {} plan limit of {limit}",
                     selected_plan.name.to_lowercase()
                 );
-                return Ok(err(
+                return Err(unprocessable("member-limit-exceeded", &message));
-                    StatusCode::UNPROCESSABLE_ENTITY,
-                    "member-limit-exceeded",
-                    &message,
-                ));
             }
         }
     }
 
-    match api.command.update_relay(&relay).await {
+    api.command
-        Ok(()) => Ok(ok(StatusCode::OK, relay)),
+        .update_relay(&relay)
-        Err(e) => {
+        .await
-            if matches!(map_unique_error(&e), Some("subdomain-exists")) {
+        .map_err(map_relay_write_error)?;
-                Ok(err(
+    ok(relay)
-                    StatusCode::UNPROCESSABLE_ENTITY,
-                    "subdomain-exists",
-                    "subdomain already exists",
-                ))
-            } else {
-                Ok(err(
-                    StatusCode::INTERNAL_SERVER_ERROR,
-                    "internal",
-                    &e.to_string(),
-                ))
-            }
-        }
-    }
 }
 
 pub async fn deactivate_relay(
     State(api): State<Arc<Api>>,
     AuthedPubkey(auth): AuthedPubkey,
     Path(id): Path<String>,
-) -> Result<Response, ApiError> {
+) -> ApiResult {
-    let relay = match api.query.get_relay(&id).await {
+    let relay = api.get_relay_or_404(&id).await?;
-        Ok(Some(r)) => r,
-        Ok(None) => return Ok(err(StatusCode::NOT_FOUND, "not-found", "relay not found")),
-        Err(e) => {
-            return Ok(err(
-                StatusCode::INTERNAL_SERVER_ERROR,
-                "internal",
-                &e.to_string(),
-            ));
-        }
-    };
-
     api.require_admin_or_tenant(&auth, &relay.tenant)?;
 
     if relay.status == RELAY_STATUS_INACTIVE || relay.status == RELAY_STATUS_DELINQUENT {
-        return Ok(err(
+        return Err(bad_request("relay-is-inactive", "relay is already inactive"));
-            StatusCode::BAD_REQUEST,
-            "relay-is-inactive",
-            "relay is already inactive",
-        ));
     }
 
-    match api.command.deactivate_relay(&relay).await {
+    api.command
-        Ok(()) => Ok(ok(StatusCode::OK, ())),
+        .deactivate_relay(&relay)
-        Err(e) => Ok(err(
+        .await
-            StatusCode::INTERNAL_SERVER_ERROR,
+        .map_err(internal)?;
-            "internal",
+    ok(())
-            &e.to_string(),
-        )),
-    }
 }
 
 pub async fn reactivate_relay(
     State(api): State<Arc<Api>>,
     AuthedPubkey(auth): AuthedPubkey,
     Path(id): Path<String>,
-) -> Result<Response, ApiError> {
+) -> ApiResult {
-    let relay = match api.query.get_relay(&id).await {
+    let relay = api.get_relay_or_404(&id).await?;
-        Ok(Some(r)) => r,
-        Ok(None) => return Ok(err(StatusCode::NOT_FOUND, "not-found", "relay not found")),
-        Err(e) => {
-            return Ok(err(
-                StatusCode::INTERNAL_SERVER_ERROR,
-                "internal",
-                &e.to_string(),
-            ));
-        }
-    };
-
     api.require_admin_or_tenant(&auth, &relay.tenant)?;
 
     if relay.status == RELAY_STATUS_ACTIVE {
-        return Ok(err(
+        return Err(bad_request("relay-is-active", "relay is already active"));
-            StatusCode::BAD_REQUEST,
-            "relay-is-active",
-            "relay is already active",
-        ));
     }
 
-    match api.command.activate_relay(&relay).await {
+    api.command.activate_relay(&relay).await.map_err(internal)?;
-        Ok(()) => Ok(ok(StatusCode::OK, ())),
+    ok(())
-        Err(e) => Ok(err(
-            StatusCode::INTERNAL_SERVER_ERROR,
-            "internal",
-            &e.to_string(),
-        )),
-    }
 }
 
 // --- helpers ----------------------------------------------------------------
@@ -447,6 +302,18 @@ fn prepare_relay(api: &Api, mut relay: Relay) -> Result<Relay, RelayValidationEr
     Ok(relay)
 }
 
+fn validation_error(error: RelayValidationError) -> ApiError {
+    unprocessable(error.code(), error.message())
+}
+
+fn map_relay_write_error(e: anyhow::Error) -> ApiError {
+    if matches!(map_unique_error(&e), Some("subdomain-exists")) {
+        unprocessable("subdomain-exists", "subdomain already exists")
+    } else {
+        internal(e)
+    }
+}
+
 const SUBDOMAIN_LABEL_MAX_LEN: usize = 63;
 const RESERVED_SUBDOMAIN_LABELS: [&str; 2] = ["api", "admin"];
 
@@ -536,11 +403,3 @@ fn validate_subdomain_label(subdomain: &str) -> Result<(), SubdomainValidationEr
 
     Ok(())
 }
-
-fn relay_validation_error_response(error: RelayValidationError) -> Response {
-    err(
-        StatusCode::UNPROCESSABLE_ENTITY,
-        error.code(),
-        error.message(),
-    )
-}

backend/src/routes/stripe.rs

@@ -3,13 +3,12 @@ use std::sync::Arc;
 use axum::{
     body::Bytes,
     extract::{Path, Query as QueryParams, State},
-    http::{HeaderMap, StatusCode},
+    http::HeaderMap,
-    response::Response,
 };
 use serde::Deserialize;
 
 use crate::api::{Api, AuthedPubkey};
-use crate::web::{ApiError, err, ok};
+use crate::web::{ApiResult, bad_request, internal, ok};
 
 #[derive(Deserialize)]
 pub struct StripeSessionParams {
@@ -21,22 +20,16 @@ pub async fn create_stripe_session(
     AuthedPubkey(auth): AuthedPubkey,
     Path(pubkey): Path<String>,
     QueryParams(params): QueryParams<StripeSessionParams>,
-) -> Result<Response, ApiError> {
+) -> ApiResult {
     api.require_admin_or_tenant(&auth, &pubkey)?;
     let tenant = api.get_tenant_or_404(&pubkey).await?;
 
-    match api
+    let url = api
         .billing
         .stripe_create_portal_session(&tenant.stripe_customer_id, params.return_url.as_deref())
         .await
-    {
+        .map_err(internal)?;
-        Ok(url) => Ok(ok(StatusCode::OK, serde_json::json!({ "url": url }))),
+    ok(serde_json::json!({ "url": url }))
-        Err(e) => Ok(err(
-            StatusCode::INTERNAL_SERVER_ERROR,
-            "internal",
-            &e.to_string(),
-        )),
-    }
 }
 
 /// Stripe webhook endpoint. Authenticated via `Stripe-Signature` verification
@@ -45,19 +38,18 @@ pub async fn stripe_webhook(
     State(api): State<Arc<Api>>,
     headers: HeaderMap,
     body: Bytes,
-) -> Response {
+) -> ApiResult {
     let signature = headers
         .get("Stripe-Signature")
         .and_then(|v| v.to_str().ok())
         .unwrap_or("");
 
-    let payload = match std::str::from_utf8(&body) {
+    let payload = std::str::from_utf8(&body)
-        Ok(s) => s,
+        .map_err(|_| bad_request("bad-request", "invalid payload"))?;
-        Err(_) => return err(StatusCode::BAD_REQUEST, "bad-request", "invalid payload"),
-    };
 
-    match api.billing.handle_webhook(payload, signature).await {
+    api.billing
-        Ok(()) => ok(StatusCode::OK, ()),
+        .handle_webhook(payload, signature)
-        Err(e) => err(StatusCode::BAD_REQUEST, "webhook-error", &e.to_string()),
+        .await
-    }
+        .map_err(|e| bad_request("webhook-error", &e.to_string()))?;
+    ok(())
 }

backend/src/routes/tenants.rs

@@ -3,15 +3,13 @@ use std::sync::Arc;
 use axum::{
     Json,
     extract::{Path, State},
-    http::StatusCode,
-    response::Response,
 };
-use serde::{Deserialize, Serialize};
 use chrono::Utc;
+use serde::{Deserialize, Serialize};
 
 use crate::api::{Api, AuthedPubkey};
 use crate::models::Tenant;
-use crate::web::{ApiError, err, map_unique_error, ok};
+use crate::web::{ApiResult, internal, map_unique_error, ok};
 
 #[derive(Serialize)]
 pub struct TenantResponse {
@@ -46,23 +44,14 @@ pub struct UpdateTenantRequest {
 pub async fn list_tenants(
     State(api): State<Arc<Api>>,
     AuthedPubkey(auth): AuthedPubkey,
-) -> Result<Response, ApiError> {
+) -> ApiResult {
     api.require_admin(&auth)?;
 
-    match api.query.list_tenants().await {
+    let tenants = api.query.list_tenants().await.map_err(internal)?;
-        Ok(tenants) => Ok(ok(
+    ok(tenants
-            StatusCode::OK,
+        .into_iter()
-            tenants
+        .map(TenantResponse::from)
-                .into_iter()
+        .collect::<Vec<_>>())
-                .map(TenantResponse::from)
-                .collect::<Vec<_>>(),
-        )),
-        Err(e) => Ok(err(
-            StatusCode::INTERNAL_SERVER_ERROR,
-            "internal",
-            &e.to_string(),
-        )),
-    }
 }
 
 /// Creates the tenant row for the calling pubkey. Idempotent: if the tenant
@@ -71,60 +60,37 @@ pub async fn list_tenants(
 pub async fn create_tenant(
     State(api): State<Arc<Api>>,
     AuthedPubkey(pubkey): AuthedPubkey,
-) -> Result<Response, ApiError> {
+) -> ApiResult {
-    match api.query.get_tenant(&pubkey).await {
+    if let Some(t) = api.query.get_tenant(&pubkey).await.map_err(internal)? {
-        Ok(Some(t)) => Ok(ok(StatusCode::OK, TenantResponse::from(t))),
+        return ok(TenantResponse::from(t));
-        Ok(None) => {
+    }
-            let stripe_customer_id = match api.billing.stripe_create_customer(&pubkey).await {
-                Ok(id) => id,
-                Err(e) => {
-                    return Ok(err(
-                        StatusCode::INTERNAL_SERVER_ERROR,
-                        "stripe-customer-create-failed",
-                        &e.to_string(),
-                    ));
-                }
-            };
 
-            let tenant = Tenant {
+    let stripe_customer_id = api
-                pubkey: pubkey.clone(),
+        .billing
-                nwc_url: String::new(),
+        .stripe_create_customer(&pubkey)
-                nwc_error: None,
+        .await
-                created_at: Utc::now().timestamp(),
+        .map_err(internal)?;
-                stripe_customer_id,
-                stripe_subscription_id: None,
-                past_due_at: None,
-            };
 
-            match api.command.create_tenant(&tenant).await {
+    let tenant = Tenant {
-                Ok(()) => Ok(ok(StatusCode::OK, TenantResponse::from(tenant))),
+        pubkey: pubkey.clone(),
-                Err(e) if matches!(map_unique_error(&e), Some("pubkey-exists")) => {
+        nwc_url: String::new(),
-                    match api.query.get_tenant(&pubkey).await {
+        nwc_error: None,
-                        Ok(Some(t)) => Ok(ok(StatusCode::OK, TenantResponse::from(t))),
+        created_at: Utc::now().timestamp(),
-                        Ok(None) => Ok(err(
+        stripe_customer_id,
-                            StatusCode::INTERNAL_SERVER_ERROR,
+        stripe_subscription_id: None,
-                            "internal",
+        past_due_at: None,
-                            "tenant row missing after unique-constraint race",
+    };
-                        )),
+
-                        Err(e) => Ok(err(
+    match api.command.create_tenant(&tenant).await {
-                            StatusCode::INTERNAL_SERVER_ERROR,
+        Ok(()) => ok(TenantResponse::from(tenant)),
-                            "internal",
+        Err(e) if matches!(map_unique_error(&e), Some("pubkey-exists")) => {
-                            &e.to_string(),
+            match api.query.get_tenant(&pubkey).await {
-                        )),
+                Ok(Some(t)) => ok(TenantResponse::from(t)),
-                    }
+                Ok(None) => Err(internal("tenant row missing after unique-constraint race")),
-                }
+                Err(e) => Err(internal(e)),
-                Err(e) => Ok(err(
-                    StatusCode::INTERNAL_SERVER_ERROR,
-                    "internal",
-                    &e.to_string(),
-                )),
             }
         }
-        Err(e) => Ok(err(
+        Err(e) => Err(internal(e)),
-            StatusCode::INTERNAL_SERVER_ERROR,
-            "internal",
-            &e.to_string(),
-        )),
     }
 }
 
@@ -132,10 +98,10 @@ pub async fn get_tenant(
     State(api): State<Arc<Api>>,
     AuthedPubkey(auth): AuthedPubkey,
     Path(pubkey): Path<String>,
-) -> Result<Response, ApiError> {
+) -> ApiResult {
     api.require_admin_or_tenant(&auth, &pubkey)?;
     let tenant = api.get_tenant_or_404(&pubkey).await?;
-    Ok(ok(StatusCode::OK, TenantResponse::from(tenant)))
+    ok(TenantResponse::from(tenant))
 }
 
 pub async fn update_tenant(
@@ -143,7 +109,7 @@ pub async fn update_tenant(
     AuthedPubkey(auth): AuthedPubkey,
     Path(pubkey): Path<String>,
     Json(payload): Json<UpdateTenantRequest>,
-) -> Result<Response, ApiError> {
+) -> ApiResult {
     api.require_admin_or_tenant(&auth, &pubkey)?;
     let mut tenant = api.get_tenant_or_404(&pubkey).await?;
 
@@ -152,52 +118,40 @@ pub async fn update_tenant(
         if nwc_url.is_empty() {
             tenant.nwc_url = String::new();
         } else {
-            tenant.nwc_url = api
+            tenant.nwc_url = api.env.encrypt(&nwc_url).map_err(internal)?;
-                .env
-                .encrypt(&nwc_url)
-                .map_err(|e| ApiError::Internal(e.to_string()))?;
         }
     }
 
-    match api.command.update_tenant(&tenant).await {
+    api.command.update_tenant(&tenant).await.map_err(internal)?;
-        Ok(()) => {
+
-            // When NWC is first connected, attempt to pay any outstanding open invoices.
+    // When NWC is first connected, attempt to pay any outstanding open invoices.
-            if nwc_previously_empty && !tenant.nwc_url.is_empty() {
+    if nwc_previously_empty && !tenant.nwc_url.is_empty() {
-                let billing = api.billing.clone();
+        let billing = api.billing.clone();
-                let tenant_clone = tenant.clone();
+        let tenant_clone = tenant.clone();
-                tokio::spawn(async move {
+        tokio::spawn(async move {
-                    if let Err(e) = billing.pay_outstanding_nwc_invoices(&tenant_clone).await {
+            if let Err(e) = billing.pay_outstanding_nwc_invoices(&tenant_clone).await {
-                        tracing::error!(
+                tracing::error!(
-                            error = %e,
+                    error = %e,
-                            pubkey = %tenant_clone.pubkey,
+                    pubkey = %tenant_clone.pubkey,
-                            "pay_outstanding_nwc_invoices failed after NWC setup"
+                    "pay_outstanding_nwc_invoices failed after NWC setup"
-                        );
+                );
-                    }
-                });
             }
-            Ok(ok(StatusCode::OK, TenantResponse::from(tenant)))
+        });
-        }
-        Err(e) => Ok(err(
-            StatusCode::INTERNAL_SERVER_ERROR,
-            "internal",
-            &e.to_string(),
-        )),
     }
+    ok(TenantResponse::from(tenant))
 }
 
 pub async fn list_tenant_relays(
     State(api): State<Arc<Api>>,
     AuthedPubkey(auth): AuthedPubkey,
     Path(pubkey): Path<String>,
-) -> Result<Response, ApiError> {
+) -> ApiResult {
     api.require_admin_or_tenant(&auth, &pubkey)?;
 
-    match api.query.list_relays_for_tenant(&pubkey).await {
+    let relays = api
-        Ok(relays) => Ok(ok(StatusCode::OK, relays)),
+        .query
-        Err(e) => Ok(err(
+        .list_relays_for_tenant(&pubkey)
-            StatusCode::INTERNAL_SERVER_ERROR,
+        .await
-            "internal",
+        .map_err(internal)?;
-            &e.to_string(),
+    ok(relays)
-        )),
-    }
 }

backend/src/web.rs

@@ -1,7 +1,11 @@
 //! General-purpose HTTP helpers shared across route handlers.
 //!
-//! This module owns the wire response envelopes (`ok` / `err`), the
+//! Success builders (`res`, `ok`, `created`) return [`ApiResult`] so they
-//! `ApiError` type that route handlers return, and a few stateless utilities.
+//! can sit at the end of a handler without an `Ok(..)` wrap. Error builders
+//! (`err`, `not_found`, `forbidden`, …) return [`ApiError`] so they compose
+//! with `.map_err(...)` and with explicit `Err(...)` returns.
+
+use std::fmt::Display;
 
 use axum::{
     Json,
@@ -10,8 +14,24 @@ use axum::{
 };
 use serde::Serialize;
 
+pub struct ApiError(pub Box<Response>);
+
+impl IntoResponse for ApiError {
+    fn into_response(self) -> Response {
+        *self.0
+    }
+}
+
+impl From<Response> for ApiError {
+    fn from(r: Response) -> Self {
+        Self(Box::new(r))
+    }
+}
+
+pub type ApiResult = Result<Response, ApiError>;
+
 #[derive(Serialize)]
-pub struct OkResponse<T: Serialize> {
+pub struct DataResponse<T: Serialize> {
     pub data: T,
     pub code: &'static str,
 }
@@ -22,40 +42,23 @@ pub struct ErrorResponse {
     pub code: String,
 }
 
-#[derive(Debug)]
+// --- success builders (return ApiResult) ------------------------------------
-pub enum ApiError {
+
-    Unauthorized(anyhow::Error),
+pub fn res<T: Serialize>(status: StatusCode, data: T) -> ApiResult {
-    Forbidden(&'static str),
+    Ok((status, Json(DataResponse { data, code: "ok" })).into_response())
-    NotFound(&'static str),
-    Client {
-        status: StatusCode,
-        code: &'static str,
-        message: &'static str,
-    },
-    Internal(String),
 }
 
-impl IntoResponse for ApiError {
+pub fn ok<T: Serialize>(data: T) -> ApiResult {
-    fn into_response(self) -> Response {
+    res(StatusCode::OK, data)
-        match self {
-            Self::Unauthorized(e) => err(StatusCode::UNAUTHORIZED, "unauthorized", &e.to_string()),
-            Self::Forbidden(message) => err(StatusCode::FORBIDDEN, "forbidden", message),
-            Self::NotFound(message) => err(StatusCode::NOT_FOUND, "not-found", message),
-            Self::Client {
-                status,
-                code,
-                message,
-            } => err(status, code, message),
-            Self::Internal(message) => err(StatusCode::INTERNAL_SERVER_ERROR, "internal", &message),
-        }
-    }
 }
 
-pub fn ok<T: Serialize>(status: StatusCode, data: T) -> Response {
+pub fn created<T: Serialize>(data: T) -> ApiResult {
-    (status, Json(OkResponse { data, code: "ok" })).into_response()
+    res(StatusCode::CREATED, data)
 }
 
-pub fn err(status: StatusCode, code: &str, message: &str) -> Response {
+// --- error builders (return ApiError) ---------------------------------------
+
+pub fn err(status: StatusCode, code: &str, message: &str) -> ApiError {
     (
         status,
         Json(ErrorResponse {
@@ -64,8 +67,39 @@ pub fn err(status: StatusCode, code: &str, message: &str) -> Response {
         }),
     )
         .into_response()
+        .into()
 }
 
+pub fn unauthorized(reason: impl Display) -> ApiError {
+    err(StatusCode::UNAUTHORIZED, "unauthorized", &reason.to_string())
+}
+
+pub fn forbidden(message: &str) -> ApiError {
+    err(StatusCode::FORBIDDEN, "forbidden", message)
+}
+
+pub fn not_found(message: &str) -> ApiError {
+    err(StatusCode::NOT_FOUND, "not-found", message)
+}
+
+pub fn bad_request(code: &str, message: &str) -> ApiError {
+    err(StatusCode::BAD_REQUEST, code, message)
+}
+
+pub fn unprocessable(code: &str, message: &str) -> ApiError {
+    err(StatusCode::UNPROCESSABLE_ENTITY, code, message)
+}
+
+pub fn internal(reason: impl Display) -> ApiError {
+    err(
+        StatusCode::INTERNAL_SERVER_ERROR,
+        "internal",
+        &reason.to_string(),
+    )
+}
+
+// --- misc utilities ---------------------------------------------------------
+
 pub fn parse_bool_default(value: i64, default: i64) -> i64 {
     if value == 0 || value == 1 {
         value