feat: 전역 API 에러 안전망 도입 및 개별 훅 에러 처리 정리

[iOdiO89]

작업 요약

• 전역 에러 안전망을 도입해, 개별 훅에 흩어져 있던 5xx·네트워크 에러 처리를 한곳으로 모았습니다.

작업 내용

1. 공통 에러 메시지 유틸 추가 — getApiErrorMessage

• 5xx·네트워크: 공통 "일시적인 오류예요. 잠시 후 다시 시도해 주세요." 문구
• 4xx: 서버 detail 우선, 없으면 "요청을 처리하지 못했어요."

2. 전역 mutation / query 에러 안전망 (queryClient.ts)

MutationCache / QueryCache에 전역 onError를 붙여 에러 처리 책임을 정리했습니다.

• mutation
  • 401 → 전역 인터셉터(apis/client.ts)가 refresh·redirect로 처리하므로 양보 (이중 토스트 방지)
  • 5xx·네트워크 → 전역이 단독 처리: 공통 토스트 + Sentry.captureException
  • 4xx → 개별 onError가 있으면 양보, 없으면 generic fallback 토스트
• query
  • 토스트 없이 Sentry 로깅만 (사용자 표시는 error boundary / isError가 담당)

3. 개별 훅 정리 — 전역 안전망에 위임

• 비어있는 onError 삭제: 실질 동작 없이 형식만 있던 핸들러 제거 (useDeleteWishes, useDeleteTournament)
• 개별 훅의 5xx 토스트 분기 제거: 5xx는 전역이 단독 처리하므로 개별 훅에서 중복 분기 제거 (useDeleteWish, usePostTournamentOCR, usePatchWish, useDeleteTournamentItem) → 4xx 분기만 남김

4. 정책 문서 추가 (docs/spec/)

• error-handling-policy.md — 4xx 개별 / 5xx 전역, query는 로깅만 등 에러 처리 정책
• api-status-audit.md — 현재 API 에러 대응 현황 감사
• ownership.md — 역할 분배

정책 요약

구분	처리 위치	사용자 표시
401	전역 인터셉터 (refresh·redirect)	토스트 X
mutation 4xx	개별 훅 (없으면 전역 fallback)	토스트 O
mutation 5xx·네트워크	전역 단독	공통 토스트 O + Sentry
query 실패	전역 (boundary/isError가 표시)	토스트 X + Sentry

연관 이슈

closes #299

Summary by CodeRabbit

• New Features
  • 요청 실패 시 표시되는 오류 문구를 통일하는 유틸과 전역 에러 안전망(뮤테이션/쿼리)이 추가되었습니다.
• Bug Fixes
  • 삭제/수정/OCR 등 일부 화면에서 4xx/5xx별 토스트 표시 및 리다이렉트 동작이 더 간결하고 일관되게 정리되었습니다.
  • 불필요한 서버 오류 토스트가 줄어 사용자 피드백이 개선되었습니다.
• Documentation
  • 에러 처리 규약, API 상태 대응 감사, 페이지 단위 오너십 가이드 문서가 추가되었습니다.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
depromeet	Ready	Preview, Comment	Jul 10, 2026 7:29am

[github-actions]

Discord 스레드 연동용 메타데이터입니다. discord-pr-bot 워크플로가 자동 생성하며, 수정·삭제하면 PR 과 Discord 알림 연동이 끊깁니다.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: e65dc5b1-7301-4f90-85a8-167f24341d9c

📥 Commits

Reviewing files that changed from the base of the PR and between 96332de and 76b17d5.

📒 Files selected for processing (3)

• docs/spec/api-status-audit.md
• docs/spec/error-handling-policy.md
• docs/spec/ownership.md

💤 Files with no reviewable changes (1)

• docs/spec/ownership.md

✅ Files skipped from review due to trivial changes (1)

• docs/spec/api-status-audit.md

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/spec/error-handling-policy.md

---

📝 Walkthrough

Walkthrough

전역 mutation/query 에러 처리와 공통 메시지 변환이 추가되었고, 개별 mutation 훅의 500 전용·빈 에러 처리가 정리되었다. 에러 정책, API 상태 감사, 코드 오너십 문서도 추가되었다.

Changes

전역 에러 안전망과 개별 훅 정리

Layer / File(s)	Summary
전역 에러 유틸과 QueryClient apps/web/src/utils/getApiErrorMessage.ts, apps/web/src/utils/queryClient.ts	Axios 에러 메시지 변환 유틸을 추가하고, mutation/query 전역 에러 처리를 상태 코드와 개별 핸들러 유무에 따라 분기한다.
개별 삭제·패치 훅 정리 apps/web/src/app/archive/_hooks/useDeleteWishes.ts, apps/web/src/app/archive/wish/[id]/_hooks/useDeleteWish.ts, apps/web/src/app/archive/wish/[id]/_hooks/usePatchWish.ts, apps/web/src/app/tournament/[id]/_common/_hooks/useDeleteTournamentItem.ts, apps/web/src/hooks/useDeleteTournament.ts, apps/web/src/hooks/usePostTournamentOCR.ts	위시·토너먼트·OCR mutation 훅에서 빈 에러 핸들러와 500 전용 토스트를 제거하고, 4xx 처리와 기존 라우팅을 정리한다.

에러 정책·감사·오너십 문서

Layer / File(s)	Summary
에러 정책과 API 상태 감사 docs/spec/error-handling-policy.md, docs/spec/api-status-audit.md	에러 처리 계층, status별 책임, 전역 안전망 예시, API 영역별 대응 현황과 잔여 작업을 문서화한다.
오너십 문서 docs/spec/ownership.md	페이지 담당표, 공유 접점, 개인별 기술 과제와 운영 규칙을 정의한다.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Mutation as Mutation
  participant QueryClient as QueryClient
  participant Toast as toast
  participant Sentry as Sentry

  Mutation->>QueryClient: 에러 전달
  QueryClient->>QueryClient: HTTP 상태 및 개별 onError 확인
  alt 5xx 또는 네트워크 오류
    QueryClient->>Toast: getApiErrorMessage(error) 표시
    QueryClient->>Sentry: captureException(error)
  else 4xx 및 개별 onError 없음
    QueryClient->>Toast: 공통 에러 메시지 표시
    QueryClient->>Sentry: captureException(error)
  else 4xx 및 개별 onError 있음
    QueryClient-->>Mutation: 개별 에러 처리에 위임
  end

Loading

Possibly related PRs

• TeamPiKi/PiKi-Client#127: 토너먼트 아이템 삭제 훅의 동일한 500 토스트 및 에러 분기와 관련된다.
• TeamPiKi/PiKi-Client#135: 토너먼트 삭제 mutation의 기존 onError 흐름을 직접 이어받는다.

Suggested labels: refactor

Suggested reviewers: kanghaeun, ychany, soyeong0115

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	제목이 전역 API 에러 안전망 도입과 개별 훅 에러 처리 정리라는 핵심 변경을 잘 요약합니다.
Linked Issues check	✅ Passed	MutationCache 전역 onError, queryCache 로깅 전용, 5xx 제거, 비어 있는 훅 정리 등 요구사항과 대체로 일치합니다.
Out of Scope Changes check	✅ Passed	변경 내용은 API 에러 처리와 관련 문서 추가에 집중되어 있어 링크된 이슈 범위를 벗어난 코드는 보이지 않습니다.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/299-global-error-handling

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/spec/ownership.md`:
- Around line 16-21: 소셜로그인 담당 구분이 두 군데에서 서로 다르게 적혀 있어 라우팅 기준이 혼동됩니다.
ownership.md의 “위시 + 소셜로그인” 범위와 `/login`, `/auth/callback/[provider]`가 포함된 페이지 표를
하나의 기준으로 통일하고, `소영` 또는 `선아/공동 리뷰` 중 실제 담당 원칙에 맞게 한쪽으로 정리해 중복 표기를 제거하세요. `위시 +
소셜로그인`, `/login`, `/auth/callback/[provider]`, `토큰 인프라 · 계정 · 플랫폼 + 공동 리뷰` 항목이
같은 책임 체계를 가리키도록 문구를 맞추면 됩니다.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 7555d5ae-15df-4ef6-aefa-5862c48c69db

📥 Commits

Reviewing files that changed from the base of the PR and between dad6817 and 2a76b4e.

📒 Files selected for processing (11)

• apps/web/src/app/archive/_hooks/useDeleteWishes.ts
• apps/web/src/app/archive/wish/[id]/_hooks/useDeleteWish.ts
• apps/web/src/app/archive/wish/[id]/_hooks/usePatchWish.ts
• apps/web/src/app/tournament/[id]/_common/_hooks/useDeleteTournamentItem.ts
• apps/web/src/hooks/useDeleteTournament.ts
• apps/web/src/hooks/usePostTournamentOCR.ts
• apps/web/src/utils/getApiErrorMessage.ts
• apps/web/src/utils/queryClient.ts
• docs/spec/api-status-audit.md
• docs/spec/error-handling-policy.md
• docs/spec/ownership.md

💤 Files with no reviewable changes (5)

• apps/web/src/app/tournament/[id]/_common/_hooks/useDeleteTournamentItem.ts
• apps/web/src/hooks/usePostTournamentOCR.ts
• apps/web/src/hooks/useDeleteTournament.ts
• apps/web/src/app/archive/wish/[id]/_hooks/usePatchWish.ts
• apps/web/src/app/archive/_hooks/useDeleteWishes.ts

[coderabbitai]

Actionable comments posted: 3

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

apps/web/src/app/archive/wish/[id]/_hooks/useDeleteWish.ts (1)

22-37: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

403/404 외 4xx가 처리되지 않아 조용히 삼켜집니다.

onError가 403/404만 토스트를 띄우므로, 400·409·422 등 다른 4xx가 발생하면 로컬도 무시하고, queryClient.ts의 전역 mutationCache.onError도 mutation.options.onError가 존재한다는 이유만으로 양보(return)합니다. 결과적으로 해당 실패는 사용자에게 전혀 표시되지 않습니다.

401은 전역 인터셉터가, 5xx는 전역 mutationCache가 전담하므로, 이 훅에서는 그 외 모든 4xx를 커버하도록 조건을 넓히는 것이 안전합니다.

🐛 제안: 도달 가능한 4xx 전체를 커버

     onError: error => {
       if (!isAxiosError<ApiErrorResponseT>(error) || !error.response) return;

       const {
         status,
         data: { detail },
       } = error.response;

+      /** 401은 전역 인터셉터, 5xx는 전역 mutationCache가 전담 */
+      if (status === 401 || status >= 500) return;
+
       const clientErrorMessage = detail ?? '요청을 처리하지 못했습니다.';

-      /**
-       * 403: 위시 삭제 권한 없음
-       * 404: 위시 존재하지 않음
-       */
-      if (status === 403 || status === 404) toast.error(clientErrorMessage);
+      toast.error(clientErrorMessage);
     },

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/web/src/app/archive/wish/`[id]/_hooks/useDeleteWish.ts around lines 22 -
37, The local error handling in useDeleteWish only surfaces 403 and 404, so
other reachable 4xx responses are dropped before the global mutation handler can
show anything. Update the onError logic in useDeleteWish to treat all non-401
4xx responses as user-facing errors by broadening the status check (while still
letting 401 and 5xx remain handled elsewhere), and keep using the existing
clientErrorMessage derived from error.response.data.detail.

🧹 Nitpick comments (1)

apps/web/src/utils/queryClient.ts (1)

34-38: 🚀 Performance & Scalability | 🔵 Trivial | 💤 Low value

쿼리 4xx 에러도 무조건 Sentry로 전송됩니다.

queryCache.onError는 상태코드 구분 없이 모든 쿼리 실패를 캡처합니다. 404 등 예상 가능한 클라이언트 에러까지 Sentry에 누적되면 노이즈가 커질 수 있습니다. 5xx·네트워크 에러만 캡처하도록 제한하는 것을 고려해 보세요.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@apps/web/src/utils/queryClient.ts` around lines 34 - 38, The QueryCache
onError handler in queryClient is sending every failed query to Sentry,
including expected 4xx responses. Update the onError logic in queryCache to
inspect the error before calling Sentry.captureException, and only capture 5xx
or network-related failures while skipping expected client errors like 404. Use
the existing QueryCache setup in queryClient to keep the change localized and
preserve all other behavior.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/spec/api-status-audit.md`:
- Around line 18-33: 현재 표의 “무피드백/조용히 삼킴” 분류가 MutationCache.onError 전역 안전망을 반영하지
않아 과장되어 보입니다. `useDeleteTournament.ts`, `useDeleteWishes.ts`,
`usePostWishRefresh.ts`, `usePostRecordMatch`, `usePostGuestLogin`, `getAuthUrl`
사용부, `usePostNotificationsRead`, `useGetNotifications`, `useFcmTokenSync` 등은 전부
“사용자 피드백 완전 부재”가 아니라 “로컬 맞춤 UX 없음”으로 재분류하고, `MutationCache.onError`가 보장하는 최소
토스트가 있는 케이스와 진짜로 전역 처리까지 없는 케이스를 분리해 문구를 정리하세요. 또한 `usePostTournamentStart`,
`usePostCreateTournament`, `usePostWishOCR`, `usePatchWish`,
`usePostTournamentOCR`, `usePatchTournamentItem`의 502 미대응은 별도 항목으로 유지하되, 실제로 전역
onError가 커버하는지 여부에 맞춰 설명을 맞추고, 미구현 엔드포인트와 Dead code는 현재 상태를 그대로 두되 “호출 코드 없음/소비처
없음”으로 구분해 주세요.

In `@docs/spec/error-handling-policy.md`:
- Around line 20-29: Update the fenced example block in error-handling-policy so
it uses an explicit language tag instead of an unlabeled fence, which is
triggering markdownlint MD040. Locate the first fenced block in the document and
change it to a typed fence such as ts or text so the markdown validator
recognizes it consistently. Keep the rest of the content unchanged.

In `@docs/spec/ownership.md`:
- Around line 102-105: The `CODEOWNERS` guidance in the ownership spec describes
behavior incorrectly. Update the wording in the ownership section to state that
`CODEOWNERS` only auto-assigns reviewers, and that approval enforcement comes
from branch protection with “Require review from Code Owners”; also change the
precedence rule to reflect that `CODEOWNERS` uses the last matching pattern, not
the most specific path. Reference the ownership bullets and the `CODEOWNERS`
examples so the text matches actual behavior.

---

Outside diff comments:
In `@apps/web/src/app/archive/wish/`[id]/_hooks/useDeleteWish.ts:
- Around line 22-37: The local error handling in useDeleteWish only surfaces 403
and 404, so other reachable 4xx responses are dropped before the global mutation
handler can show anything. Update the onError logic in useDeleteWish to treat
all non-401 4xx responses as user-facing errors by broadening the status check
(while still letting 401 and 5xx remain handled elsewhere), and keep using the
existing clientErrorMessage derived from error.response.data.detail.

---

Nitpick comments:
In `@apps/web/src/utils/queryClient.ts`:
- Around line 34-38: The QueryCache onError handler in queryClient is sending
every failed query to Sentry, including expected 4xx responses. Update the
onError logic in queryCache to inspect the error before calling
Sentry.captureException, and only capture 5xx or network-related failures while
skipping expected client errors like 404. Use the existing QueryCache setup in
queryClient to keep the change localized and preserve all other behavior.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 443207f9-68b9-437a-b28d-212840fb39e7

📥 Commits

Reviewing files that changed from the base of the PR and between dad6817 and 96332de.

📒 Files selected for processing (11)

• apps/web/src/app/archive/_hooks/useDeleteWishes.ts
• apps/web/src/app/archive/wish/[id]/_hooks/useDeleteWish.ts
• apps/web/src/app/archive/wish/[id]/_hooks/usePatchWish.ts
• apps/web/src/app/tournament/[id]/_common/_hooks/useDeleteTournamentItem.ts
• apps/web/src/hooks/useDeleteTournament.ts
• apps/web/src/hooks/usePostTournamentOCR.ts
• apps/web/src/utils/getApiErrorMessage.ts
• apps/web/src/utils/queryClient.ts
• docs/spec/api-status-audit.md
• docs/spec/error-handling-policy.md
• docs/spec/ownership.md

💤 Files with no reviewable changes (5)

• apps/web/src/hooks/usePostTournamentOCR.ts
• apps/web/src/app/archive/_hooks/useDeleteWishes.ts
• apps/web/src/hooks/useDeleteTournament.ts
• apps/web/src/app/archive/wish/[id]/_hooks/usePatchWish.ts
• apps/web/src/app/tournament/[id]/_common/_hooks/useDeleteTournamentItem.ts