Error Handling (backend → BFF → client)

{
  "success": false,
  "error": {
    "code": "AUTH_INVALID_CREDENTIALS",
    "message": "이메일 또는 비밀번호가 일치하지 않습니다.",
    "details": [
      { "field": "email", "code": "INVALID_FORMAT", "message": "..." }
    ]
  }
}

sealed class DomainException(
  val httpStatus: HttpStatus,
  val code: String,
  message: String,
) : RuntimeException(message)
 
class InvalidCredentialsException(...) : DomainException(UNAUTHORIZED, "AUTH_INVALID_CREDENTIALS", ...)
class ExpiredRefreshTokenException(...) : DomainException(UNAUTHORIZED, "AUTH_REFRESH_EXPIRED", ...)
class DuplicateEmailException(email) : DomainException(409, "DUPLICATE_EMAIL", ...)
// ... 등

// apps/admin/src/lib/backend.ts (의사)
export const callBackend = async (
  path: string,
  init: RequestInit,
  session: Session,
): Promise<Response> => {
  await refreshIfNeeded(session);
  let res: Response;
  try {
    res = await fetch(BACKEND_URL + path, withAuth(init, session));
  } catch (err) {
    // 네트워크 도달 실패 — 생성자: (status, body: unknown, code?: string)
    throw new BackendCallError(502, err, "BACKEND_UNREACHABLE");
  }
  if (res.status === 401) {
    // refresh 한 번 시도
    try { await forceRefresh(session); } catch { session.destroy(); throw ... }
    res = await fetch(BACKEND_URL + path, withAuth(init, session));
    if (res.status === 401) { session.destroy(); throw ... 401 ... }
  }
  return res;
};
 
// BFF route handler 에서
try {
  const res = await callBackend(...);
  if (!res.ok) {
    if (res.status >= 500) {
      // 5xx → session 유지 + 502 BACKEND_ERROR (잠시 후 다시 시도)
      return NextResponse.json({ code: "BACKEND_ERROR" }, { status: 502 });
    }
    // 4xx 인증 외 → backend code/status 그대로 surface
    const body = await res.json();
    return NextResponse.json(body, { status: res.status });
  }
  return NextResponse.json(await res.json());
} catch (err) {
  if (err instanceof BackendCallError) {
    return NextResponse.json({ code: err.code }, { status: err.status });
  }
  throw err;
}

// apps/admin/src/lib/error.ts
// backend ErrorResponse({ error: { code } }) 와 BFF normalize({ code }) 두 형태를 모두 흡수.
// 인자는 응답 payload(JSON) — 에러 객체가 아니다. client/server 양쪽에서 import 가능.
export const extractCode = (body: unknown): string | undefined => {
  if (typeof body !== "object" || body === null) return undefined;
  const nested = (body as { error?: { code?: unknown } }).error;
  if (nested && typeof nested.code === "string") return nested.code;
  const root = (body as { code?: unknown }).code;
  return typeof root === "string" ? root : undefined;
};
 
// 사용 — payload(JSON body)를 넘긴다 (에러 객체 X)
try {
  await login.mutateAsync({ email, password });
} catch (err) {
  const code = extractCode((err as ApiError).body);
  switch (code) {
    case "AUTH_INVALID_CREDENTIALS":
      toast.error("이메일 또는 비밀번호가 일치하지 않습니다.");
      break;
    case "BACKEND_ERROR":
    case "BACKEND_UNREACHABLE":
      toast.error("잠시 후 다시 시도해 주세요.");
      break;
    default:
      toast.error("알 수 없는 오류");
  }
}

// queryFn 에서 ApiError 던지면 react-query 가 error state 로
const { data, error, isError } = useQuery({
  queryKey: ["me"],
  queryFn: () => apiFetch<MeResponse>("/api/auth/me", { method: "GET" }),
});
if (isError && extractCode((error as ApiError)?.body) === "BACKEND_ERROR") {
  // 사용자에게 "잠시 후 다시" 안내, retry 가능
}