feat(errors): add ApiError envelope + robust frontend parser

Closes the long tail of "[object Object]" toasts that surfaced when a
backend route returned a structured error body (e.g. 402
plan_limit_hit) and the frontend's ``new Error(detail)`` stringified
the dict. Also normalises Pydantic 422 validation responses through the
same envelope so a missing field surfaces as
"field required (name)" rather than the raw [{loc, msg, type}] array.

Three pieces, one shape:

  backend/app/core/errors.py  — new ApiError(status, code, message, **extras)
                                produces {"detail": {error, message, ...}} on
                                the wire. Drop-in for the existing 402
                                plan_limit_hit pattern; opt-in for new
                                endpoints. Existing HTTPException(detail="...")
                                sites keep working through the new frontend
                                parser without migration.

  backend/app/main.py         — RequestValidationError exception handler
                                rewrites Pydantic 422 envelope from the
                                default array shape into ApiError's flat
                                shape, with a one-line summary message
                                pointing at the first failing field and
                                the raw error list preserved under
                                detail.errors for clients that need the
                                breakdown.

  frontend/src/services/api.js — parseErrorBody handles all three current
                                wire shapes (ApiError dict, legacy string,
                                top-level rate-limit envelope) plus the
                                Pydantic array as a defensive fallback for
                                in-flight deploys. The thrown Error always
                                has .message / .code / .status / .detail
                                so every consumer can either show the
                                message in a toast or branch on a stable
                                code without regex-matching text.

MCP coexistence: ApiError is REST-only by docstring. ``app.mount("/mcp",
mcp_app)`` already isolates FastMCP as an ASGI sub-app, so no exception
handler registered on the parent FastAPI app reaches into the MCP
layer. MCP tools keep raising ToolError; the JSON-RPC error envelope
the protocol mandates stays untouched.

Tests:
  backend/tests/test_errors.py  — 6 cases (ApiError minimal/extras/reserved
                                  keys/serialization + 422 handler envelope
                                  + summary)  → 235 backend tests total
  frontend/tests/services/api.test.js — extended from 5 → 9 cases
                                  covering each wire shape  → 33 frontend
                                  tests total

No mass-migration of the existing ~30 raise HTTPException(detail="...")
sites. The new parser handles their shape correctly; future endpoints
opt into ApiError when they want structured fields. Lower blast radius
than a wholesale rewrite, same end-user benefit.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: Sbussiso

backend/app/core/errors.py

@@ -0,0 +1,121 @@
+"""Standardized error envelope for the REST surface (`/api/*` routes).
+
+Background
+----------
+``raise HTTPException(detail="some string")`` was the original pattern across
+the codebase, and the frontend parser in ``services/api.js`` evolved around
+it.  When a few routes started returning structured detail dicts (notably the
+402 plan-limit-hit body in ``app.api.hls.push_segment``), ``new Error(detail)``
+on the frontend produced ``"[object Object]"`` for any consumer that hadn't
+been written to specifically pull a ``message`` field out.
+
+Rather than mass-migrate every existing ``HTTPException`` site at once, this
+module adds:
+
+  - ``ApiError`` — drop-in replacement that produces a structured envelope.
+    Use it on new endpoints, and migrate old ones opportunistically when you
+    touch them.
+  - The frontend's ``services/api.js`` knows about all three current shapes
+    (``string``, ``dict``, Pydantic-422 ``list[dict]``) so it never falls
+    through to the ``[object Object]`` path regardless of which backend
+    pattern produced the response.
+
+MCP coexistence
+---------------
+``ApiError`` is for FastAPI REST handlers only.  MCP tools at ``POST /mcp``
+must keep raising ``fastmcp.exceptions.ToolError`` — the JSON-RPC error
+envelope is fixed by the MCP protocol and is what every MCP client (Claude,
+Cursor, custom agents) is built to consume.  ``app.mount("/mcp", mcp_app)``
+mounts FastMCP as an ASGI sub-app, so exception handlers registered on the
+parent FastAPI app don't reach into the MCP layer either way — the surfaces
+are isolated by construction, this docstring just records the design.
+
+Do NOT call ``raise ApiError`` inside helpers shared between REST handlers
+and MCP tool implementations.  If you have to share business logic, either
+return a result object that each side translates, or raise a plain Python
+exception that each side catches and re-wraps.  See
+``backend/app/mcp/server.py`` lines 503/532/572/595/etc. for the existing
+``ToolError`` translation pattern.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import HTTPException
+
+
+class ApiError(HTTPException):
+    """Structured error response for the REST surface.
+
+    Parameters
+    ----------
+    status_code : int
+        HTTP status code.  4xx for client errors, 5xx for server.
+    code : str
+        Machine-readable error code (snake_case).  Frontend consumers can
+        branch on ``e.code === "plan_limit_hit"`` etc. instead of regex-
+        matching the message text.
+    message : str
+        Human-readable sentence the frontend can show to the user as-is.
+        Should be operator-friendly, not a stack-trace fragment.
+    **extra
+        Optional structured fields to embed in the envelope.  Stay flat and
+        JSON-serializable; the frontend reads them off ``e.detail.<key>``.
+
+    Wire format
+    -----------
+    ::
+
+        {
+          "detail": {
+            "error": "<code>",
+            "message": "<message>",
+            "<extra-key>": "<extra-value>",
+            ...
+          }
+        }
+
+    The flat shape mirrors the existing 402 plan-limit-hit body, so
+    ``services/api.js``'s parser handles both old call sites and new
+    ``ApiError`` ones identically.
+
+    Examples
+    --------
+    Simple not-found::
+
+        raise ApiError(404, "camera_not_found", "Camera not found")
+
+    With structured fields::
+
+        raise ApiError(
+            402,
+            "plan_limit_hit",
+            f"Camera over the {plan} plan limit",
+            plan=plan,
+            max_cameras=max_cams,
+            camera_name=camera.name,
+        )
+    """
+
+    def __init__(
+        self,
+        status_code: int,
+        code: str,
+        message: str,
+        **extra: Any,
+    ) -> None:
+        detail: dict[str, Any] = {"error": code, "message": message}
+        # Flatten extras into the envelope rather than nesting them.  Matches
+        # the existing 402 shape so the frontend doesn't need a special case.
+        for key, value in extra.items():
+            if key in ("error", "message"):
+                # These are reserved by the envelope itself.  Refuse silently
+                # rather than overwriting — easier to spot in tests than a
+                # confusing message swap at runtime.
+                raise ValueError(
+                    f"ApiError extra key {key!r} collides with reserved "
+                    f"envelope field; rename the kwarg",
+                )
+            detail[key] = value
+        super().__init__(status_code=status_code, detail=detail)

backend/app/main.py

@@ -140,6 +140,51 @@ async def rate_limit_exceeded_handler(request: Request, exc: RateLimitExceeded)
 app.add_exception_handler(RateLimitExceeded, rate_limit_exceeded_handler)
 app.add_middleware(SlowAPIMiddleware)
 
+
+# ── Pydantic validation errors → ApiError envelope ──────────────────
+#
+# FastAPI's default 422 body for a request that fails Pydantic
+# validation is a list of dicts:
+#
+#     {"detail": [{"loc": [...], "msg": "...", "type": "..."}]}
+#
+# That's machine-friendly but unreadable to a human, and the frontend's
+# error parser used to stringify the array into something like
+# "[object Object]" before we taught it about the shape.  Funnel
+# validation failures through the same envelope ApiError uses, so the
+# REST surface produces one shape regardless of whether the failure
+# came from a hand-raised exception or Pydantic's auto-validation.
+#
+# Behaviour on the frontend stays consistent: services/api.js looks at
+# body.detail.message and shows it as-is.  Test code can still inspect
+# body.detail.errors for the structured per-field breakdown.
+from fastapi.exceptions import RequestValidationError  # noqa: E402
+
+@app.exception_handler(RequestValidationError)
+async def validation_exception_handler(request: Request, exc: RequestValidationError):
+    """Rewrite Pydantic 422 envelope to match ApiError's shape."""
+    errors = exc.errors()
+    # Build a one-line summary out of the first failing field — that's
+    # what gets shown in the toast.  The full error list is preserved
+    # under detail.errors for callers (and tests) that want the breakdown.
+    if errors:
+        first = errors[0]
+        loc = ".".join(str(p) for p in first.get("loc", []) if p != "body")
+        msg = first.get("msg", "Validation failed")
+        summary = f"{msg} ({loc})" if loc else msg
+    else:
+        summary = "Request validation failed"
+    return JSONResponse(
+        status_code=422,
+        content={
+            "detail": {
+                "error": "validation_failed",
+                "message": summary,
+                "errors": errors,  # full list for clients that want it
+            },
+        },
+    )
+
 # Get frontend URL from environment (set in fly.toml or .env)
 frontend_url = os.getenv("FRONTEND_URL", "http://localhost:5173")
 

backend/tests/test_errors.py

@@ -0,0 +1,158 @@
+"""Tests for the ApiError class + the 422 validation exception handler.
+
+The class itself is small enough to test directly; the handler is wired into
+``app.main`` so we exercise it through the FastAPI test client by hitting an
+existing endpoint with an invalid body and asserting the rewritten envelope.
+"""
+
+import pytest
+from fastapi import FastAPI, status
+from fastapi.testclient import TestClient
+from pydantic import BaseModel
+
+from app.core.errors import ApiError
+
+
+# ── ApiError unit tests ────────────────────────────────────────────
+
+
+def test_apierror_minimal_envelope():
+    """Status, code, and message land in the right slots."""
+    err = ApiError(404, "camera_not_found", "Camera not found")
+    assert err.status_code == 404
+    assert err.detail == {"error": "camera_not_found", "message": "Camera not found"}
+
+
+def test_apierror_extras_flatten_into_detail():
+    """Optional kwargs (plan, max_cameras, etc.) sit alongside error/message
+    in the same flat dict — matches the existing 402 plan-limit-hit shape so
+    the frontend's parser handles both old and new sites identically."""
+    err = ApiError(
+        402,
+        "plan_limit_hit",
+        "Camera over the Free plan limit",
+        plan="Free",
+        max_cameras=5,
+        camera_name="Front Door",
+    )
+    assert err.status_code == 402
+    assert err.detail == {
+        "error": "plan_limit_hit",
+        "message": "Camera over the Free plan limit",
+        "plan": "Free",
+        "max_cameras": 5,
+        "camera_name": "Front Door",
+    }
+
+
+def test_apierror_rejects_reserved_extra_keys():
+    """``error`` is envelope-reserved; collisions raise loudly so a typo
+    can't silently overwrite the machine-readable code in detail.
+
+    (``message`` is also reserved but Python catches that one earlier with
+    a built-in TypeError because it's the third positional parameter — no
+    extra check needed for that key.)"""
+    with pytest.raises(ValueError, match="reserved envelope field"):
+        ApiError(400, "bad_request", "Body invalid", error="something_else")
+
+
+def test_apierror_serializes_through_fastapi_handler():
+    """End-to-end: ApiError raised from a route handler reaches the wire as
+    ``{detail: {error, message, ...}}`` — the shape services/api.js parses."""
+    app = FastAPI()
+
+    @app.get("/raise")
+    def _raise():
+        raise ApiError(
+            418,
+            "im_a_teapot",
+            "Cannot brew coffee",
+            requested="coffee",
+            available=["tea"],
+        )
+
+    with TestClient(app) as client:
+        resp = client.get("/raise")
+    assert resp.status_code == 418
+    assert resp.json() == {
+        "detail": {
+            "error": "im_a_teapot",
+            "message": "Cannot brew coffee",
+            "requested": "coffee",
+            "available": ["tea"],
+        },
+    }
+
+
+# ── 422 validation handler integration ─────────────────────────────
+#
+# We rebuild a fresh FastAPI app for these tests rather than reusing the
+# real `app.main.app`. Two reasons:
+#   - Adding routes to the live app post-startup falls through to the SPA
+#     middleware (returns index.html, not the test endpoint's response).
+#   - The validation handler is the unit under test; isolating it from
+#     the rest of the production middleware stack makes failures easy to
+#     attribute.
+# We import the handler function directly from main.py and re-register it
+# on the test app so we're testing the same code that ships.
+
+
+def _make_validation_test_app():
+    """Build a fresh FastAPI app with only the validation handler from
+    main.py wired in. Used to exercise the 422 → envelope rewrite without
+    pulling in the SPA middleware / Clerk / database lifecycle."""
+    from fastapi.exceptions import RequestValidationError
+
+    from app.main import validation_exception_handler
+
+    app = FastAPI()
+    app.add_exception_handler(RequestValidationError, validation_exception_handler)
+
+    class Body(BaseModel):
+        name: str
+        port: int
+
+    @app.post("/validate")
+    def _endpoint(body: Body):
+        return {"ok": True, "name": body.name}
+
+    return app
+
+
+def test_validation_error_rewritten_to_apierror_envelope():
+    """A request that fails Pydantic validation should come back through the
+    same envelope shape as ApiError — error code, human message, and the
+    raw Pydantic error list preserved under detail.errors for clients that
+    want the per-field breakdown."""
+    app = _make_validation_test_app()
+
+    with TestClient(app) as client:
+        # Missing required field "port".
+        resp = client.post("/validate", json={"name": "x"})
+
+    assert resp.status_code == status.HTTP_422_UNPROCESSABLE_CONTENT
+    body = resp.json()
+
+    assert "detail" in body
+    detail = body["detail"]
+    assert detail["error"] == "validation_failed"
+    assert isinstance(detail["message"], str) and detail["message"]
+    # Full per-field list preserved for callers that need it.
+    assert isinstance(detail["errors"], list) and detail["errors"]
+    first = detail["errors"][0]
+    assert "loc" in first and "msg" in first
+
+
+def test_validation_error_handler_summarises_first_field_in_message():
+    """The summary message points at the first failing field so a toast
+    can show ``"Field required (name)"`` instead of a generic message."""
+    app = _make_validation_test_app()
+
+    with TestClient(app) as client:
+        resp = client.post("/validate", json={})
+
+    body = resp.json()
+    msg = body["detail"]["message"]
+    # Either "name" or "port" — both are missing, ordering depends on Pydantic
+    # internals but at least one should appear in the summary.
+    assert any(field in msg for field in ("name", "port"))