設計
【設計】プロダクトエラーの重要度分類 — critical / warning / notice をどう決めるか
Share
エラー通知の重要度を critical / warning / notice の3段階に分類するとき、「プロダクトが止まるか」を唯一の判断基準にしました。実際に全APIルートを分類した過程と判断理由を共有します。
はじめに
エラー通知を導入するとき、最初に悩むのが「どのエラーをどのレベルにするか」です。最初は Stripe の設定エラーだけ critical にしていましたが、見直していくうちに、明確な判断基準が必要だと気づきました。
この記事でわかること
-
critical / warning / notice の判断基準
-
実際の分類結果とその理由
-
最初の分類から見直したポイント
-
迷ったらどう判断するかの指針
対象読者
-
エラー監視やアラートの設計を考えている方
-
個人開発・小規模チームで運用している方
1. 判断基準はシンプルに1つ
「そのエラーが起きたら、プロダクトとして使えなくなるか？」
Yes → critical、No → warning または notice
複雑な分類軸を作ると迷います。「ユーザーが使えるか」という一点だけを判断基準にしたことで、分類がスムーズになりました。
3段階の定義
| レベル | 意味 | 判断基準 | アクション |
|---|---|---|---|
| critical | プロダクトが機能しない | ユーザーがコア機能を使えない | 即対応 |
| warning | 一部に影響 | プロダクト自体は動くが、なにかがおかしい | 次回作業時に確認 |
| notice | 情報として把握 | ユーザーに影響なし、運用データとして有用 | 定期的に確認 |
2. critical に分類したものとその理由
Stripe（決済）— 全部 critical
Stripe のエラーはほぼ全て critical にしました。
| エラー | 理由 |
|---|---|
| Webhook SECRET未設定・署名検証失敗 | 課金してもPro反映されない、解約が処理されない |
| Checkout Session作成失敗 | ユーザーが課金できない |
| Portal作成失敗 | プラン管理・解約ができない |
| アカウント削除時の解約失敗 | アカウント削除したのに課金が続く |
特に「アカウント削除したのに課金が続く」は最初 warning にしていましたが、よく考えると課金継続リスクがあるので critical に格上げしました。
チャット（コア機能）— 全部 critical
このアプリは「チャット」が主機能です。チャットができない = プロダクトとして成立しない。
-
OpenAI API エラー→応答が返せない
-
チャットセッション取得エラー→チャット画面が開けない
ログイン・認証 — critical
ログインできないのは「プロダクトが使えない」の典型です。
Cron（バッチ処理）— 混在
-
CRON_SECRET未設定→ critical（全cronが止まる） -
個別ジョブ失敗→ warning（翌日のサマリーが生成されない程度、ユーザーが即困るわけではない）
-
ジョブ内の致命的エラー（DB接続障害等）→ critical
3. warning に分類したものとその理由
warning は「プロダクト自体は動くが、なにかがおかしい」状態です。
| カテゴリ | 例 | 理由 |
|---|---|---|
| 日記操作 | PUT/PATCH/DELETE失敗 | チャットはできる、日記の編集ができないだけ |
| ユーザー設定 | プロフィール・パスワード更新 | コア機能に影響なし |
| 管理者操作 | ユーザー管理・通知管理 | エンドユーザーに影響なし |
| チャット補助 | Web検索・画像認識・記憶検索 | チャット自体は動く、補助機能が落ちるだけ |
| 通知 | 取得・既読処理 | アプリのコア機能ではない |
「迷ったら warning」でOK
分類に迷ったら warning にしておくのが安全です。critical にしすぎるとノイズが多くなり、本当に重要な通知が埋もれます。
4. notice に分類したもの
| カテゴリ | 例 | 理由 |
|---|---|---|
| レートリミット | ログイン試行超過 | エラーではなく正常な保護動作。おかしな人がいるかも程度 |
| R2クリーンアップ | 画像削除失敗 | ユーザーに影響なし、ストレージが残るだけ |
5. 見直しのプロセス
最初の分類からいくつか見直しました。その過程を共有します。
warning → critical に格上げしたもの
当初は Stripe の設定エラーだけ critical にしていましたが、実際に「プロダクトとして成り立つか？」を広く考えたら、以下が格上げになりました。
-
Stripe Webhook イベント処理エラー — 課金してもPro反映されない
-
Checkout Session 作成失敗 — ユーザーが課金できない
-
OpenAI API エラー — チャットがコア機能
-
アカウント削除時のStripe解約失敗 — 課金継続リスク
判断が難しかったもの
-
cron 個別ジョブ失敗: サマリーが生成されないのは困るが、ユーザーが「今困る」わけではない → warning
-
Web検索・Gemini API Key 未設定: チャット自体は動く、オプショナル機能 → warning
6. 分類のチェックリスト
新しいエラーハンドリングを追加するときに使えるチェックリストです。
-
そのエラーが起きたら、ユーザーはアプリの主要機能を使えるか？ → No なら critical
-
エンドユーザーに影響があるか？ → Yes なら warning
-
運用上知っておきたいか？ → Yes なら notice
-
どれにも当てはまらないなら通知不要
まとめ
-
判断基準は「プロダクトが止まるか」の1点だけ
-
critical は「即対応」、warning は「次回確認」、notice は「定期確認」
-
迷ったら warning。critical を増やしすぎるとノイズになる
-
最初の分類で完璧でなくていい。運用しながら見直す
-
分類基準をドキュメント化しておくと、新しいエラー追加時に迷わない
