Feat(#292): react-query 전역 mutation 에러 토스트 안전망 추가

[stringnine]

📌 관련 이슈

• Closes [Feat] react-query 전역 에러 처리 (mutation 실패 토스트 안전망) #292

🏷️ PR 타입

• ✨ 기능 추가 (Feature)
• 🐛 버그 수정 (Bug Fix)
• ♻️ 리팩토링 (Refactoring)
• 🗑️ 코드 제거 (Chore)
• 📝 문서 수정 (Documentation)
• 🎨 스타일 변경 (Style)
• ✅ 테스트 추가 (Test)

📝 작업 내용

개별 처리되지 않은 mutation 실패가 조용히 사라지던 문제를 막기 위해 react-query 전역 에러 토스트 안전망을 추가했습니다.

• MutationCache.onError 추가 → 개별 처리되지 않은 mutation 실패를 자동으로 에러 토스트 표시
• 중복 토스트 방지
  • meta.suppressGlobalErrorToast 옵트아웃 → 호출부에서 자체 에러 UI를 표시하는 mutation은 제외
  • 에러 페이지로 리다이렉트되는 에러(5xx 등)는 토스트 생략 (getErrorRedirectRoute)
• 원시 기술 메시지 노출 방지 → meta.errorMessage → 서버 message → 안전한 기본 문구 순으로 추출
• 쿼리 retry 정책 → 4xx(클라이언트 에러)는 비재시도, 그 외만 2회 재시도
• react-query mutationMeta 타입 보강
• client.ts: getErrorRedirectRoute() 헬퍼 export (기존 리다이렉트 판단 로직 재사용)

옵트아웃 처리한 mutation (자체 피드백 존재 → 중복 방지)

Mutation	사유
useUseCredit	ChatInput 자체 토스트 + 낙관적 롤백
useCancelSubscription / useResumeSubscription	SubscriptionTabContent 자체 토스트
useUpgradeSubscription	PricingPage 자체 토스트
useDeleteNotesBulk	DeleteNotesModal 인라인 에러
useCreateNote	useHomeSend 자체 onError 토스트

새로 안전망이 적용된 곳 (기존엔 조용히 실패)

• useDeleteNote(RecentNotes), useUpdateNoteTitle(SidebarNoteItem)의 catch {} → 이제 실패 시 토스트 표시

✅ 체크리스트

공통

• 셀프 리뷰를 완료했습니다
• 코드 리뷰를 받을 준비가 완료되었습니다
• pnpm tsc --noEmit 타입 체크를 통과했습니다
• 브랜치명 컨벤션을 준수했습니다 (type/이슈번호-작업명)

📎 기타 참고사항

• 동작 확인: 미처리 mutation(노트 이름 변경)을 임시로 실패시켜 우측 상단 에러 토스트 표시를 로컬에서 검증했습니다.
• 5xx 리다이렉트 vs 토스트의 세부 정책 정리는 [Feat] API 네트워크 견고성 강화 (axios timeout/오프라인 + 에러 리다이렉트 정책 정리) #293에서 다룰 예정이며, 본 PR은 '중복 방지' 수준만 포함합니다.
• 쿼리 에러는 토스트가 과도해질 수 있어(백그라운드 refetch 등) 전역 토스트 대상에서 제외하고 retry 정책만 조정했습니다.

Summary by CodeRabbit

• Bug Fixes
  • 에러 발생 시 중복된 에러 메시지 표시를 방지하도록 개선했습니다.
  • 특정 작업에서 불필요한 에러 알림을 억제하여 사용자 경험을 개선했습니다.
  • 에러 메시지 표시 로직을 안정적으로 개선했습니다.

[coderabbitai]

📝 Walkthrough

Walkthrough

전역 MutationCache.onError 핸들러를 추가하여 처리되지 않은 mutation 실패 시 자동으로 토스트를 표시하고, suppressGlobalErrorToast 메타 플래그와 getErrorRedirectRoute 헬퍼로 중복 표시를 방지하며, 개별 뮤테이션에서 선택적으로 억제한다.

Changes

전역 mutation 에러 처리 및 안전망

Layer / File(s)	Summary
전역 에러 처리 기반 구축 src/app/providers/query_provider.tsx, src/shared/api/client.ts	React Query의 mutationMeta 타입을 suppressGlobalErrorToast, errorMessage 필드로 확장하고, resolveErrorMessage 헬퍼로 axios 응답 메시지 추출, MutationCache.onError 핸들러에서 조건부 토스트 표시, query retry를 4xx 비재시도 + 2회 재시도로 설정. getErrorRedirectRoute 헬퍼로 토스트와 에러 리다이렉트 중복 방지.
개별 뮤테이션에서 전역 토스트 억제 src/features/notes/hooks/useNotes.ts, src/features/settings/hooks/useCredit.ts, src/features/settings/hooks/useUser.ts	useCreateNote, useDeleteNotesBulk, useUseCredit, useCancelSubscription, useUpgradeSubscription, useResumeSubscription에 meta: { suppressGlobalErrorToast: true }를 추가하여 개별 에러 처리가 있는 뮤테이션에서는 전역 토스트가 표시되지 않도록 설정.

Sequence Diagram

sequenceDiagram
  participant Mutation as Mutation<br/>(실패)
  participant MutationCache as MutationCache<br/>.onError
  participant CheckSuppress as suppressGlobalErrorToast<br/>체크
  participant CheckRedirect as getErrorRedirectRoute<br/>체크
  participant ResolveMsg as resolveErrorMessage<br/>메시지 추출
  participant Toast as showErrorToast<br/>(표시)
  
  Mutation->>MutationCache: 실패 발생
  MutationCache->>CheckSuppress: meta.suppressGlobalErrorToast 확인
  CheckSuppress-->>MutationCache: true면 중단
  MutationCache->>CheckRedirect: getErrorRedirectRoute(error) 호출
  CheckRedirect-->>MutationCache: 리다이렉트 경로<br/>(있으면 중단, 없으면 계속)
  MutationCache->>ResolveMsg: 에러 메시지 추출
  ResolveMsg-->>MutationCache: data.message 또는<br/>DEFAULT_ERROR_MESSAGE
  MutationCache->>Toast: 메시지와 함께 토스트 표시

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related issues

• #293: 에러 리다이렉트(getErrorRedirectRoute) 및 axios 클라이언트의 에러 처리 동작 개선으로 전역 토스트와 전체 페이지 리다이렉트 간 역할 분담 구현

Poem

🐰 mutation이 넘어져도

토스트가 날아 사용자 귀에 닿고,

이미 챙길 땐 조용히,

중복은 막고 깔끔하게,

에러 안전망 완성! 🥕✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description check	✅ Passed	PR 설명이 필수 섹션(관련 이슈, PR 타입, 작업 내용, 체크리스트)을 모두 포함하고 있으며, 변경사항을 상세히 기술하고 있습니다.
Linked Issues check	✅ Passed	PR의 모든 코드 변경사항이 이슈 #292의 요구사항을 충족합니다: MutationCache.onError 추가, 중복 토스트 방지 메커니즘(suppressGlobalErrorToast, getErrorRedirectRoute), 4xx 비재시도 정책, mutationMeta 타입 보강이 모두 구현되었습니다.
Out of Scope Changes check	✅ Passed	모든 변경사항이 이슈 #292의 범위 내에 있습니다. 전역 에러 토스트 안전망과 관련된 파일들만 수정되었으며, 기존 토큰 관리 및 axios 인터셉터 로직은 유지되었습니다.
Title check	✅ Passed	Pull request 제목이 변경사항의 핵심을 명확하게 설명하고 있습니다. 제목은 react-query 전역 mutation 에러 토스트 안전망 추가라는 주요 변경사항을 정확하게 반영하고 있습니다.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/292-global-error-toast

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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