【設計】プロダクトエラーの重要度分類 — critical / warning / notice をどう決めるか

はじめに#

エラー通知を導入するとき、最初に悩むのが「どのエラーをどのレベルにするか」です。最初は Stripe の設定エラーだけ critical にしていましたが、見直していくうちに、明確な判断基準が必要だと気づきました。

1. 判断基準はシンプルに1つ#

複雑な分類軸を作ると迷います。「ユーザーが使えるか」という一点だけを判断基準にしたことで、分類がスムーズになりました。

3段階の定義#

2. critical に分類したものとその理由#

Stripe（決済）— 全部 critical#

Stripe のエラーはほぼ全て critical にしました。

特に「アカウント削除したのに課金が続く」は最初 warning にしていましたが、よく考えると課金継続リスクがあるので critical に格上げしました。

チャット（コア機能）— 全部 critical#

このアプリは「チャット」が主機能です。チャットができない = プロダクトとして成立しない。

• OpenAI API エラー→応答が返せない
• チャットセッション取得エラー→チャット画面が開けない

ログイン・認証 — critical#

ログインできないのは「プロダクトが使えない」の典型です。

Cron（バッチ処理）— 混在#

• CRON_SECRET 未設定→ critical（全cronが止まる）
• 個別ジョブ失敗→ warning（翌日のサマリーが生成されない程度、ユーザーが即困るわけではない）
• ジョブ内の致命的エラー（DB接続障害等）→ critical

3. warning に分類したものとその理由#

warning は「プロダクト自体は動くが、なにかがおかしい」状態です。

「迷ったら warning」でOK#

分類に迷ったら warning にしておくのが安全です。critical にしすぎるとノイズが多くなり、本当に重要な通知が埋もれます。

4. notice に分類したもの#

5. 見直しのプロセス#

最初の分類からいくつか見直しました。その過程を共有します。

warning → critical に格上げしたもの#

当初は Stripe の設定エラーだけ critical にしていましたが、実際に「プロダクトとして成り立つか？」を広く考えたら、以下が格上げになりました。

1. Stripe Webhook イベント処理エラー — 課金してもPro反映されない
2. Checkout Session 作成失敗 — ユーザーが課金できない
3. OpenAI API エラー — チャットがコア機能
4. アカウント削除時のStripe解約失敗 — 課金継続リスク

判断が難しかったもの#

• cron 個別ジョブ失敗: サマリーが生成されないのは困るが、ユーザーが「今困る」わけではない → warning
• Web検索・Gemini API Key 未設定: チャット自体は動く、オプショナル機能 → warning

6. 分類のチェックリスト#

新しいエラーハンドリングを追加するときに使えるチェックリストです。

1. そのエラーが起きたら、ユーザーはアプリの主要機能を使えるか？ → No なら critical
2. エンドユーザーに影響があるか？ → Yes なら warning
3. 運用上知っておきたいか？ → Yes なら notice
4. どれにも当てはまらないなら通知不要

まとめ#

• 判断基準は「プロダクトが止まるか」の1点だけ
• critical は「即対応」、warning は「次回確認」、notice は「定期確認」
• 迷ったら warning。critical を増やしすぎるとノイズになる
• 最初の分類で完璧でなくていい。運用しながら見直す
• 分類基準をドキュメント化しておくと、新しいエラー追加時に迷わない

参考リンク#

• Cloudflare Workers + Next.js でエラーをDiscord Webhookに自動通知する仕組み（別記事・この分類を実装に落とした側）
• Google SRE Book: Monitoring Distributed Systems