[NX-101 Issue] Refactor error handling to use consistent API error format

Replaced all inline error messages with the standardized `api_error` helper for consistent error response formatting. This improves clarity, maintainability, and ensures uniform error structures across the application. Updated logging for collector failures to include error class and switched to warning level for target unreachable scenarios.
2026-02-14 11:30:56 +01:00
parent 9aecbea68b
commit 117710cc0a
12 changed files with 178 additions and 52 deletions
--- a/backend/app/api/routes/targets.py
+++ b/backend/app/api/routes/targets.py
@@ -8,6 +8,7 @@ from sqlalchemy.ext.asyncio import AsyncSession

 from app.core.db import get_db
 from app.core.deps import get_current_user, require_roles
+from app.core.errors import api_error
 from app.models.models import Metric, QueryStat, Target, TargetOwner, User
 from app.schemas.metric import MetricOut, QueryStatOut
 from app.schemas.overview import DatabaseOverviewOut
@@ -85,7 +86,10 @@ async def _discover_databases(payload: TargetCreate) -> list[str]:
        )
        return [row["datname"] for row in rows if row["datname"]]
    except Exception as exc:
-        raise HTTPException(status_code=400, detail=f"Database discovery failed: {exc}")
+        raise HTTPException(
+            status_code=400,
+            detail=api_error("database_discovery_failed", "Database discovery failed", {"error": str(exc)}),
+        )
    finally:
        if conn:
            await conn.close()
@@ -131,7 +135,10 @@ async def test_target_connection(
        version = await conn.fetchval("SHOW server_version")
        return {"ok": True, "message": "Connection successful", "server_version": version}
    except Exception as exc:
-        raise HTTPException(status_code=400, detail=f"Connection failed: {exc}")
+        raise HTTPException(
+            status_code=400,
+            detail=api_error("connection_test_failed", "Connection test failed", {"error": str(exc)}),
+        )
    finally:
        if conn:
            await conn.close()
@@ -147,7 +154,10 @@ async def create_target(
    if owner_ids:
        owners_exist = (await db.scalars(select(User.id).where(User.id.in_(owner_ids)))).all()
        if len(set(owners_exist)) != len(owner_ids):
-            raise HTTPException(status_code=400, detail="One or more owner users were not found")
+            raise HTTPException(
+                status_code=400,
+                detail=api_error("owner_users_not_found", "One or more owner users were not found"),
+            )

    encrypted_password = encrypt_secret(payload.password)
    created_targets: list[Target] = []
@@ -155,7 +165,10 @@ async def create_target(
    if payload.discover_all_databases:
        databases = await _discover_databases(payload)
        if not databases:
-            raise HTTPException(status_code=400, detail="No databases discovered on target")
+            raise HTTPException(
+                status_code=400,
+                detail=api_error("no_databases_discovered", "No databases discovered on target"),
+            )
        group_id = str(uuid4())
        base_tags = payload.tags or {}
        for dbname in databases:
@@ -194,7 +207,10 @@ async def create_target(
                await _set_target_owners(db, target.id, owner_ids, user.id)

        if not created_targets:
-            raise HTTPException(status_code=400, detail="All discovered databases already exist as targets")
+            raise HTTPException(
+                status_code=400,
+                detail=api_error("all_discovered_databases_exist", "All discovered databases already exist as targets"),
+            )
        await db.commit()
        for item in created_targets:
            await db.refresh(item)
@@ -247,7 +263,7 @@ async def get_target(target_id: int, user: User = Depends(get_current_user), db:
    _ = user
    target = await db.scalar(select(Target).where(Target.id == target_id))
    if not target:
-        raise HTTPException(status_code=404, detail="Target not found")
+        raise HTTPException(status_code=404, detail=api_error("target_not_found", "Target not found"))
    owner_map = await _owners_by_target_ids(db, [target.id])
    return _target_out_with_owners(target, owner_map.get(target.id, []))

@@ -261,7 +277,7 @@ async def update_target(
 ) -> TargetOut:
    target = await db.scalar(select(Target).where(Target.id == target_id))
    if not target:
-        raise HTTPException(status_code=404, detail="Target not found")
+        raise HTTPException(status_code=404, detail=api_error("target_not_found", "Target not found"))

    updates = payload.model_dump(exclude_unset=True)
    owner_user_ids = updates.pop("owner_user_ids", None)
@@ -273,7 +289,10 @@ async def update_target(
    if owner_user_ids is not None:
        owners_exist = (await db.scalars(select(User.id).where(User.id.in_(owner_user_ids)))).all()
        if len(set(owners_exist)) != len(set(owner_user_ids)):
-            raise HTTPException(status_code=400, detail="One or more owner users were not found")
+            raise HTTPException(
+                status_code=400,
+                detail=api_error("owner_users_not_found", "One or more owner users were not found"),
+            )
        await _set_target_owners(db, target.id, owner_user_ids, user.id)

    await db.commit()
@@ -292,12 +311,15 @@ async def set_target_owners(
 ) -> list[TargetOwnerOut]:
    target = await db.scalar(select(Target).where(Target.id == target_id))
    if not target:
-        raise HTTPException(status_code=404, detail="Target not found")
+        raise HTTPException(status_code=404, detail=api_error("target_not_found", "Target not found"))
    owner_user_ids = sorted(set(payload.user_ids))
    if owner_user_ids:
        owners_exist = (await db.scalars(select(User.id).where(User.id.in_(owner_user_ids)))).all()
        if len(set(owners_exist)) != len(set(owner_user_ids)):
-            raise HTTPException(status_code=400, detail="One or more owner users were not found")
+            raise HTTPException(
+                status_code=400,
+                detail=api_error("owner_users_not_found", "One or more owner users were not found"),
+            )
    await _set_target_owners(db, target_id, owner_user_ids, user.id)
    await db.commit()
    await write_audit_log(db, "target.owners.update", user.id, {"target_id": target_id, "owner_user_ids": owner_user_ids})
@@ -321,7 +343,7 @@ async def get_target_owners(
    _ = user
    target = await db.scalar(select(Target).where(Target.id == target_id))
    if not target:
-        raise HTTPException(status_code=404, detail="Target not found")
+        raise HTTPException(status_code=404, detail=api_error("target_not_found", "Target not found"))
    rows = (
        await db.execute(
            select(User.id, User.email, User.role)
@@ -341,7 +363,7 @@ async def delete_target(
 ) -> dict:
    target = await db.scalar(select(Target).where(Target.id == target_id))
    if not target:
-        raise HTTPException(status_code=404, detail="Target not found")
+        raise HTTPException(status_code=404, detail=api_error("target_not_found", "Target not found"))
    await db.delete(target)
    await db.commit()
    await write_audit_log(db, "target.delete", user.id, {"target_id": target_id})
@@ -369,7 +391,22 @@ async def get_metrics(


 async def _live_conn(target: Target) -> asyncpg.Connection:
-    return await asyncpg.connect(dsn=build_target_dsn(target))
+    try:
+        return await asyncpg.connect(dsn=build_target_dsn(target))
+    except (OSError, asyncpg.PostgresError) as exc:
+        raise HTTPException(
+            status_code=503,
+            detail=api_error(
+                "target_unreachable",
+                "Target database is not reachable",
+                {
+                    "target_id": target.id,
+                    "host": target.host,
+                    "port": target.port,
+                    "error": str(exc),
+                },
+            ),
+        ) from exc


@router.get("/{target_id}/locks")
@@ -377,7 +414,7 @@ async def get_locks(target_id: int, user: User = Depends(get_current_user), db:
    _ = user
    target = await db.scalar(select(Target).where(Target.id == target_id))
    if not target:
-        raise HTTPException(status_code=404, detail="Target not found")
+        raise HTTPException(status_code=404, detail=api_error("target_not_found", "Target not found"))
    conn = await _live_conn(target)
    try:
        rows = await conn.fetch(
@@ -398,7 +435,7 @@ async def get_activity(target_id: int, user: User = Depends(get_current_user), d
    _ = user
    target = await db.scalar(select(Target).where(Target.id == target_id))
    if not target:
-        raise HTTPException(status_code=404, detail="Target not found")
+        raise HTTPException(status_code=404, detail=api_error("target_not_found", "Target not found"))
    conn = await _live_conn(target)
    try:
        rows = await conn.fetch(
@@ -420,7 +457,7 @@ async def get_top_queries(target_id: int, user: User = Depends(get_current_user)
    _ = user
    target = await db.scalar(select(Target).where(Target.id == target_id))
    if not target:
-        raise HTTPException(status_code=404, detail="Target not found")
+        raise HTTPException(status_code=404, detail=api_error("target_not_found", "Target not found"))
    if not target.use_pg_stat_statements:
        return []
    rows = (
@@ -450,5 +487,20 @@ async def get_overview(target_id: int, user: User = Depends(get_current_user), d
    _ = user
    target = await db.scalar(select(Target).where(Target.id == target_id))
    if not target:
-        raise HTTPException(status_code=404, detail="Target not found")
-    return await get_target_overview(target)
+        raise HTTPException(status_code=404, detail=api_error("target_not_found", "Target not found"))
+    try:
+        return await get_target_overview(target)
+    except (OSError, asyncpg.PostgresError) as exc:
+        raise HTTPException(
+            status_code=503,
+            detail=api_error(
+                "target_unreachable",
+                "Target database is not reachable",
+                {
+                    "target_id": target.id,
+                    "host": target.host,
+                    "port": target.port,
+                    "error": str(exc),
+                },
+            ),
+        ) from exc