API エラーハンドリング

現在の位置づけ: 本番運用中のエラーハンドリング規約（最終更新 2026-07） 最終更新: July 2026

技術メモ: Core Principles

技術メモ: 1. No Silent Failures

// ❌ BAD: Silent Fallback
try {
  const data = await apiClient.get("/documents")
  return data
} catch (error) {
  console.warn("API failed") // Only logs!
  return getCachedData() // User never knows
}

// ✅ GOOD: User-Informed Fallback
try {
  const data = await apiClient.get("/documents")
  recordEndpointSuccess("/documents")
  return { data, isStale: false }
} catch (error) {
  recordEndpointFailure("/documents", error.message)
  toast.warning("サーバー接続エラー", {
    description: "キャッシュデータを表示しています",
  })
  return { data: getCachedData(), isStale: true }
}

技術メモ: 2. Disable Writes When Offline

Status	Read	Write
Online	✅	✅
Degraded	✅ (may be stale)	⚠️ Warn before
Offline	✅ Show cached	❌ Disabled

技術メモ: 3. Clear Status Communication

Users should ALWAYS know:

Is the app loading or frozen?
Has an error occurred?
What can they do about it?
Is the data current?

技術メモ: 4. Graceful Degradation

1. Full functionality (backend online)
      ↓
2. Degraded mode (some endpoints fail)
   - Show partial data
   - Disable affected features
      ↓
3. Read-only mode (backend offline, cache available)
   - Show cached data with indicator
   - Disable all writes
      ↓
4. Offline screen (no cache)
   - Friendly offline message
   - Retry button

技術メモ: Error Response Format

技術メモ: Standard Envelope

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description",
    "details": {},
    "correlationId": "c-cb6a1d54",
    "timestamp": "2026-01-29T12:34:56+09:00",
    "path": "/api/endpoint"
  }
}

技術メモ: HTTP Status Mapping

Error Type	Status	Description
Validation	400	Client data validation
Authentication	401	Missing/invalid auth
Authorization	403	Insufficient permissions
Not Found	404	Resource doesn't exist
Business Rule	409	Period locks, over-allocation
Rate Limit	429	Too many requests
Server Error	500	Unexpected failures

技術メモ: Error Codes Reference

技術メモ: Reconciliation Errors

Code	Message	Details
`ALLOCATION_EXCEEDS_BANK_AMOUNT`	Allocated exceeds bank transaction	`{ allocated, limit, remaining }`
`ALLOCATION_EXCEEDS_JOURNAL_LINE`	Allocated exceeds journal line	`{ allocated, limit, journalLineId }`
`ALLOCATION_DUPLICATE_PAIR`	Already paired	`{ bankTxId, journalLineId, existingId }`

技術メモ: Period Lock Errors

Code	Message	Details
`PERIOD_LOCKED`	Cannot write to locked period	`{ periodId, lockedAt, lockedBy }`
`PERIOD_LOCKED_OB`	Opening Balance read-only	`{ targetPeriod, lockedPeriods }`

技術メモ: Validation Errors

Code	Message	Details
`NON_INTEGER_JPY_AMOUNT`	Non-integer JPY detected	`{ field, value }`
`TRIAL_BALANCE_IMBALANCE`	TB doesn't balance	`{ debits, credits, difference }`

技術メモ: Tax & Evidence Errors

Code	Message	Details
`LINE_TAX_RATE_MISMATCH`	Tax rate mismatch	`{ lineRate, effectiveRate, taxCode }`
`EVIDENCE_IMMUTABLE`	Cannot delete immutable evidence	`{ documentId, preservationPeriod }`

技術メモ: Auth Errors

Code	Message	Details
`INSUFFICIENT_PERMISSIONS`	User lacks permissions	`{ required, userRole, resource }`

技術メモ: Implementation Patterns

パターン 0: ミューテーション失敗（推奨・2026-07）

ユーザー向け API 失敗は必ず 原因 + 次の一手 + 相関 ID を見せ、詰まったら 問題を報告（Mushi） へ繋げます。

import { handleMutationError } from "@/lib/mutation-error-handler"

useMutation({
  mutationFn: saveSomething,
  // 操作名のみ渡す（「〜に失敗しました」はヘルパーが付ける）
  onError: handleMutationError("保存"),
})

設定不足系 ERR_* → トーストに「設定を開く」CTA
5xx / 不明コード → 「問題を報告」→ reportErrorToMushi（error_code / request_id をタグ付き）
AI ストリームは showAiFailureToast / handleAiStreamFailure（contact-support も Mushi）
禁止: toast.error(error.message) — ESLint local/no-raw-error-message-toast

RFC 9457 の code / detail / guidance / requestId / retryable はバックエンドのカタログが SSOT です（scripts/sync-error-catalog.mjs）。

パターン 1: Centralized Hook

import { useBackendStatus } from '@/hooks/use-backend-status'

function MyComponent() {
  const { status, canWrite, refresh } = useBackendStatus()

  if (status === 'offline') {
    return <OfflineScreen featureName="書類作成" onRetry={refresh} />
  }

  return (
    <Button disabled={!canWrite} onClick={handleSave}>
      {canWrite ? '保存' : '接続エラー'}
    </Button>
  )
}

パターン 2: Wrapping API Calls

import { withStatusTracking, withErrorToast } from "@/hooks/use-backend-status"

// READ operations - track but don't toast
const result = await withStatusTracking(
  () => apiClient.get("/documents"),
  "/documents"
)

// WRITE operations - toast on failure
const result = await withErrorToast(
  () => apiClient.delete(`/documents/${id}`),
  "ドキュメントの削除に失敗しました",
  { showOfflineWarning: true }
)

パターン 3: API Module

// features/documents/apis.ts
export const documentsApi = {
  async getAll() {
    return withStatusTracking(() => apiClient.get("/documents"), "/documents")
  },

  async create(data: CreateDocumentDto) {
    return withErrorToast(
      () => apiClient.post("/documents", data),
      "ドキュメント作成に失敗しました",
      { showOfflineWarning: true }
    )
  },
}

パターン 4: Query Hook with Status

export function useDocuments() {
  const { status } = useBackendStatus()

  return useQuery({
    queryKey: ["documents"],
    queryFn: async () => {
      try {
        const result = await apiClient.get("/documents")
        recordEndpointSuccess("/documents")
        return result.data
      } catch (error) {
        recordEndpointFailure("/documents", error.message)
        throw error
      }
    },
    staleTime: status === "offline" ? Infinity : 5 * 60 * 1000,
    retry: status === "offline" ? false : 3,
  })
}

技術メモ: Component Library

Component	Usage
`BackendStatusBanner`	Full-width status banner
`BackendStatusBadge`	Small inline indicator
`OfflineScreen`	Full page offline state
`ReadOnlyModeIndicator`	Shows when writes disabled
`StaleDataIndicator`	Shows when viewing cached data

// In main layout
<BackendStatusBanner hideWhenOnline={true} />

// Next to write buttons
<ReadOnlyModeIndicator />

// When showing potentially stale data
<StaleDataIndicator lastFetched={lastFetchedAt} />

技術メモ: Audit Status

技術メモ: Summary

エラーハンドリングの実装チェックリスト（本番運用中）。

Priority	Files	Good	Fixed
P1 Critical	12	10	2
P2 High	18	18	0
P3 Medium	25	15	10
P4 Low	11	9	2
Total	75	59	16

技術メモ: Key Findings

79% files already followed good patterns - log + re-throw or TanStack Query
16 files upgraded to production-ready - Added toast + endpoint tracking
DEV-only mocks now production-safe - Throw in production, mock in dev only
All toast messages use Japanese - No raw error.message exposure

技術メモ: Production standards

Endpoint Tracking - All calls use recordEndpointSuccess/recordEndpointFailure
User Notification - Toast warnings when using fallback/cached data
No Silent Failures - All errors tracked even for non-critical UI
Environment-Aware - DEV mocks don't work in production
TanStack Query Integration - Global QueryCache handles unhandled errors

技術メモ: Maintenance Guidelines

New API files - Must use recordEndpointSuccess/recordEndpointFailure
Fallback patterns - Always show toast.warning when using cached data
DEV mocks - Use if (import.meta.env.PROD) throw error
Global errors - Use meta: { suppressErrorToast: true } to opt out

テスト観点

Online → Offline transition - Banner appears, writes disabled
Offline → Online transition - Banner disappears, writes enabled
Degraded mode - Amber indicator, affected features disabled
Initial load while offline - Shows cached or offline screen

File	Purpose
`src/hooks/use-backend-status.ts`	Centralized hook
`src/components/ui/backend-status-indicator.tsx`	UI components
`src/lib/query-config.ts`	QueryCache error handlers