データベース制約エラーのUX — 失敗を分かりやすいメッセージに変える

なぜ制約の失敗はユーザーにとってつらく感じるのか

誰かが「保存」を押したとき、期待する結果は二つのどちらかです：成功した、あるいはすぐに直せる問題がある。ところが多くの場合、ユーザーは「リクエストが失敗しました」や「問題が発生しました」といった曖昧なバナーを見るだけです。フォームはそのままで、どこもハイライトされず、ユーザーは当て推量をする羽目になります。

このギャップこそが、データベース制約エラーのUXが重要な理由です。データベースはユーザーが見ていなかったルールを強制しています：「この値は一意である必要がある」「このレコードは存在する別の項目を参照する必要がある」「このフィールドは空にできない」など。アプリがそれらのルールを曖昧なエラーで隠すと、ユーザーは自分が理解できない問題の責任を取らされたように感じます。

汎用エラーは信頼も壊します。アプリが不安定だと感じて、再試行、リロード、諦められてしまいます。業務環境では、サポートにスクリーンショット付きで連絡が来ますが、多くの場合スクリーンショットには有益な情報が含まれません。

よくある例：顧客レコードを作成して「保存に失敗しました」と表示される。同じメールで再度試しても失敗する。するとユーザーは、システムがデータを重複させているのか、失っているのか、その両方なのかと疑い始めます。

データベースは、UIで検証していても最終的な真実のソースであることが多いです。データベースは他のユーザーやバックグラウンドジョブ、統合の最新状態を見ています。したがって制約違反は起こり得るもので、正常な事態です。

良い結果とは単純です：データベースのルールを、特定のフィールドと次のアクションを指すメッセージに変えること。例えば：

• 「そのメールは既に使用されています。別のメールを使うかサインインしてください。」
• 「有効なアカウントを選んでください。選択したアカウントはもう存在しません。」
• 「電話番号は必須です。」

この記事の残りでは、その“翻訳”のやり方について説明します。自前でスタックを組む場合も、AppMasterのようなツールで作る場合も、失敗を迅速に回復できる形にします。

出会うであろう制約の種類（と意味）

多くの「リクエストが失敗しました」的な瞬間は、少数のデータベースルールから来ています。ルールの種類を特定できれば、たいていは該当するフィールドに明確なメッセージを出せます。

ここにわかりやすい言葉で一般的な制約タイプを示します：

• 一意制約（Unique constraint）：ある値がユニークでなければならない。典型例はメール、ユーザー名、請求書番号、外部IDなど。失敗はユーザーが「何か間違えた」わけではなく、既存のデータと衝突したことを意味します。
• 外部キー制約（Foreign key constraint）：あるレコードが存在する別のレコードを参照しなければならない（例：order.customer_id）。参照先が削除された、存在しなかった、あるいはUIが間違ったIDを送ったときに失敗します。
• NOT NULL制約：必須の値がデータベースレベルで欠落している。フォーム上は完全に見えても起こり得ます（例えばUIがフィールドを送っていない、APIが上書きした等）。
• チェック制約（Check constraint）：値が許容範囲外であること（例：「数量は\u003e 0であること」「ステータスは特定の値のうちの一つであること」「割引は0〜100の間」）を検査します。

厄介なのは、同じ実際の問題がデータベースやツールによって見え方が変わる点です。Postgresは制約名を返してくれることがあり便利ですが、ORMはそれを一般的な例外で包むことがあります。同じ一意制約でも「duplicate key」「unique violation」やベンダー固有のエラーコードで出ることがあります。

実用例：管理パネルで顧客を編集して保存し、失敗が返る。APIがそれが email に対する一意制約であることをUIに伝えられれば、あいまいなトーストではなくEmailフィールドの下に「このメールは既に使われています」と表示できます。

各制約タイプを、ユーザーが次にできることのヒントとして扱いましょう：別の値を選ぶ、関連レコードを選び直す、必須フィールドを埋める、などです。

良いフィールドレベルのメッセージに必要なこと

データベース制約違反は技術的なイベントですが、体験は通常の案内のように感じるべきです。良い制約エラーのUXは「何かが壊れた」から「ここを直してください」へと変え、ユーザーに推測させません。

平易な言葉を使いましょう。データベース用語（「unique index」「foreign key」など）は人が話す言葉に置き換えます。「そのメールは既に使用されています」は「duplicate key value violates unique constraint」よりずっと役に立ちます。

アクションの場所にメッセージを置いてください。エラーが明確に一つの入力に紐づいているなら、そのフィールドに表示してユーザーがすぐ直せるようにします。アクション全体に関わるエラー（例：「他で使われているため削除できません」）なら、保存ボタン付近などフォームレベルで表示して次の手順を明示します。

具体性は礼儀より勝ります。役に立つメッセージは二つの質問に答えます：何を変更すべきか、拒否された理由は何か。「別のユーザー名を選んでください」は「無効なユーザー名」より優れています。「保存前に顧客を選択してください」は「データが不足しています」より有用です。

ただし機密情報には慎重になってください。最も「親切」なメッセージが情報漏洩を招くことがあります。ログインやパスワードリセット画面で「このメールのアカウントは存在しません」と出すと攻撃者に有利になる場合があります。その場合は「該当するアカウントがあれば、メールを送信します」のように安全な表現を使いましょう。

また、複数の問題が同時に発生する可能性を考えておきましょう。単一の保存で複数の制約に引っかかることがあります。UIは複数のフィールドメッセージを同時に表示でき、画面が圧倒されないようにするべきです。

強いフィールドレベルメッセージとは、平易な言葉を使い、適切なフィールド（もしくは明確なフォームレベル）を指し、何を変更すべきかを伝え、個人情報を漏らさず、1つのレスポンスで複数エラーを扱えるものです。

APIとUIの間にエラー契約を設計する

良いUXは合意から始まります：何か失敗したとき、APIはUIに何が起きたかを正確に伝え、UIは毎回同じように表示する。契約がないと、結局誰にも役に立たない汎用トーストへ逆戻りします。

実用的なエラーの形は小さくて具体的であるべきです。安定したエラーコード、フィールド（単一入力に対応する場合）、人間向けメッセージ、ログ用の任意の詳細を持たせます。

{
  "error": {
    "code": "UNIQUE_VIOLATION",
    "field": "email",
    "message": "That email is already in use.",
    "details": {
      "constraint": "users_email_key",
      "table": "users"
    }
  }
}

重要なのは安定性です。生のデータベース文をユーザーに露出させず、UIにPostgresのエラーストリングを解析させないでください。コードはプラットフォーム（Web、iOS、Android）やエンドポイント間で一貫させます。

フィールドエラーとフォームレベルエラーを事前にどう表現するか決めておきましょう。フィールドエラーは1つの入力がブロックされていることを意味します（fieldをセットして入力の下に表示）。フォームレベルエラーは、フィールドは見た目上有効でもアクション自体が完了できない場合に使います（fieldは空にして保存ボタン付近に表示）。複数フィールドが同時に失敗する可能性があるなら、各エラーに field と code を持つ配列を返します。

レンダリングを一貫させるために、UIのルールは地味で予測可能にしてください：最初のエラーを上部に短い要約として表示し、フィールド横にもインラインで表示する。メッセージは短く実行可能にし、サインアップやプロファイル編集、管理画面などで同じ言い回しを再利用し、details はログに残して表示は message のみとします。

AppMasterで構築する場合、この契約を普通のAPI出力と同様に扱ってください。バックエンドで構造化された形を返し、生成されたWeb（Vue3）やモバイルアプリは共通のパターンでレンダリングできます。こうすることで、すべての制約違反が案内のように感じられ、クラッシュのようには見えません。

ステップバイステップ：DBエラーをフィールドメッセージに翻訳する

良いデータベース制約エラーのUXは、データベースを最初の審判ではなく最終的な判定者として扱うことから始まります。ユーザーが生のSQLテキストやスタックトレース、曖昧な「リクエストが失敗しました」を見るべきではありません。どのフィールドを直すべきか、次に何をすべきかを示すべきです。

多くのスタックで動く実用的なフロー：

1. どこでエラーを捕捉するかを決める。 データベースエラーがAPIレスポンスになる1箇所を決めます（多くはレポジトリ/DAO層かグローバルなエラーハンドラ）。これにより「時々インライン、時々トースト」といった混乱を防げます。
2. 失敗を分類する。 書き込みが失敗したら、そのカテゴリ（一意制約、外部キー、NOT NULL、チェック）を検出します。可能ならドライバのエラーコードを使い、テキスト解析は最後の手段にします。
3. 制約名をフォームのフィールドにマップする。 制約は識別子として便利ですが、UIはフィールドキーを必要とします。users_email_key -> email や orders_customer_id_fkey -> customerId のようなシンプルなルックアップをスキーマを所有するコードの近くに置いてください。
4. 安全なメッセージを生成する。 生のDBメッセージではなく、クラスごとに短くユーザーフレンドリーな文を作ります。Unique ->「この値は既に使われています」。FK ->「既存の顧客を選んでください」。NOT NULL ->「このフィールドは必須です」。Check ->「値が許可範囲外です」。
5. 構造化されたエラーを返してインラインで表示する。 一貫したペイロード（例：[{ field, code, message }]）を返します。UIではメッセージをフィールドに紐づけ、最初の失敗フィールドにスクロールしてフォーカスし、グローバルバナーは要約のみとします。

AppMasterで作るなら同じ考え方を適用します：バックエンドの一箇所でDBエラーを捕まえ、予測可能なフィールドエラー形式に翻訳してからWebやモバイルUIで入力横に表示する。これによりデータモデルが進化しても体験は一貫します。

現実的な例：3つの保存失敗と3つの適切な結果

これらの失敗はしばしば1つの汎用トーストにまとめられてしまいます。しかしそれぞれ別のメッセージが必要です。

1) サインアップ：メールが既に使われている（一意制約）

ログに出る生の失敗例： duplicate key value violates unique constraint "users_email_key"

ユーザーに見せるべき内容： 「そのメールは既に登録されています。サインインするか別のメールをお試しください。」

メッセージはEmailフィールドの横に出し、フォームの入力は維持します。可能なら「サインイン」などの二次アクションを提示して、ユーザーが次に何をすべきか迷わないようにします。

2) 注文作成：顧客がない（外部キー）

生の失敗例： insert or update on table "orders" violates foreign key constraint "orders_customer_id_fkey"

ユーザーに見せるべき内容： 「この注文には顧客を選んでください。」

これはユーザーにとって「エラー」ではなく、コンテキストが足りない状態に感じられます。Customerのセレクタを強調し、既に追加した行は保持します。もし別タブで顧客が削除されていたなら「その顧客は存在しません。別の顧客を選んでください」と明示します。

3) プロフィール更新：必須フィールドが欠けている（NOT NULL）

生の失敗例： null value in column "last_name" violates not-null constraint

ユーザーに見せるべき内容： 「姓は必須です。」

これが良い制約処理の姿です：通常のフォームのフィードバックであり、システムのクラッシュではありません。

サポートのために技術的な詳細を漏らさないよう、完全なエラーはログ（または内部のエラーパネル）に残します：リクエストIDやユーザー/セッションID、制約名（可能なら）、テーブル/フィールド、APIペイロード（機密はマスク）、タイムスタンプ、エンドポイント、そしてユーザーに見せたメッセージを含めます。

外部キーエラー：ユーザーが回復できるようにする

外部キー失敗はたいてい、ユーザーが選んだものが存在しなくなった、許可されなくなった、または現在のルールに合わないことを意味します。目的は単に失敗を説明するだけでなく、明確な次のアクションを示すことです。

ほとんどの場合、外部キーエラーは1つのフィールドにマップされます：別レコードを参照するピッカー（Customer、Project、Assigneeなど）。メッセージはユーザーが認識する名前で示し、内部IDやテーブル名は出さないでください。「Customerが存在しない（customer_id=42）」のような表示は避け、「その顧客は存在しません」が有用です。

堅実な回復パターンは、エラーを古くなった選択扱いにします。最新の一覧から再選択するよう促す（ドロップダウンを更新する、検索ピッカーを開くなど）。レコードが削除またはアーカイブされているならそう明示し、代替のアクティブな項目を案内します。ユーザーに権限がなくなっているなら「この項目を使う権限がありません」と示し、別の項目を選ぶか管理者に連絡するよう促します。関連レコードを作るのが自然な次の手順なら、「新しい顧客を作成する」といった選択肢を提示すると良いでしょう。

削除やアーカイブされたレコードはよくある罠です。UIで非アクティブ項目を文脈として表示できるなら「Archived」などと明示し選択できないようにしておくと、そもそもの失敗を防げますが、他のユーザーがデータを変更した場合には依然ハンドリングが必要です。

場合によっては外部キー失敗はフォームレベルのエラーにすべきです。どの参照が原因か特定できないとき、複数の参照が無効になっているとき、または問題が権限に関わるときはフォームレベルにします。

NOT NULLとバリデーション：エラーを予防し、それでも扱う

NOT NULLは防ぐのが最も簡単で、放置されると最も苛立たしい失敗です。必須フィールドを空にして「リクエストが失敗しました」と出るのは、データベースがUIの仕事をしているように見えます。良い制約エラーのUXとは、UIで明らかなケースをブロックし、それでも漏れた場合にAPIが明確なフィールドエラーを返すことです。

まずフォームで早期チェックを行いましょう。必須フィールドは入力の近くに明示します。単に赤いアスタリスクよりも「領収書に必要」など短いヒントが有用です。フィールドが条件付きで必須になる場合（例：「アカウント種別 = 事業 のとき会社名が必須」）、そのルールが該当時に見えるようにします。

UI検証だけでは不十分です。古いアプリ版、ネットワーク不安定、バルクインポート、自動化などで回避され得ます。API側でも同じルールを反映して、往復で無駄なラウンドトリップを避け、データベースでの失敗に備えます。

アプリ全体で言い回しを統一し、ユーザーが各メッセージの意味を学べるようにします。欠落値には「必須」、長さ制限には「長すぎます（最大50文字）」、フォーマットには「無効な形式（[email protected]の形式）」、型エラーには「数値である必要があります」といった具合です。

PATCHのような部分更新ではNOT NULLが厄介です。既存の値がある状態でフィールドを省略するPATCHは失敗すべきではありませんが、クライアントが明示的にnullや空値を送るなら失敗すべきです。このルールは一度決めて文書化し、一貫して適用してください。

実用的には三層で検証するのがよい：クライアントのフォームルール、APIリクエスト検証、そしてデータベースNOT NULLを捕捉して対応フィールドにマップする最後の安全網です。

「リクエストが失敗しました」に戻る原因となる一般的ミス

制約処理を台無しにする最速の方法は、すべての重い処理をデータベース側でやっておき、その結果を汎用トーストで隠すことです。ユーザーは制約が発火したこと自体には興味がなく、何をどう直せばよいかを知りたいだけです。

よくある失敗の一つは生のデータベース文を表示することです。duplicate key value violates unique constraint のような文は、回復可能な問題でもクラッシュのように見えます。ユーザーは怖い文言をコピーしてサポートに送るため、役に立つ情報の代わりに不安を生みます。

もう一つの罠は文字列マッチに頼ることです。ドライバを変えたりPostgresをアップグレードしたり、制約名を変えるとマッピングが効かなくなります。すると静かに「メールは既に使われています」のようなマッピングが動かなくなり、また「リクエストが失敗しました」に戻ります。安定したエラーコードとUIが理解するフィールド名を使ってください。

スキーマ変更はフィールドマッピングを壊すもっとも頻繁な原因の一つです。email を primary_email にリネームすると明確だったメッセージが行き場を失います。マッピングはマイグレーションと同じ変更セットの一部にし、テストでフィールドキーが不明な場合は目立つように失敗させてください。

UXを台無しにする大きな例は、すべての制約失敗をHTTP 500でボディなしに返すことです。これではUIは「サーバー側の問題」としか解釈できず、フィールドヒントを出せません。多くの制約失敗はユーザーが修正できるものなので、バリデーションスタイルのレスポンス（詳細つき）を返すべきです。

注意すべきパターン：

• サインアップでメールの重複を「アカウントが存在する」と断定してしまう（サインアップでは存在確認になり得る）
• 「一度に1つのエラーだけ扱う」ことで2つ目の壊れたフィールドを隠す
• ステップ型フォームで戻る/次へでエラーが消える
• 再試行が古い値を送って有効なフィールドのメッセージを上書きする
• ログに制約名やエラーコードが落ちず、バグ追跡が困難になる

例えばサインアップフォームで「メールが既に存在します」と出すとアカウントの存在を漏らす可能性があります。サインアップでは「メールを確認するか、サインインを試してください」のような中立的な文言にしつつ、エラーはメールフィールドに添えるのが安全です。

出荷前のクイックチェックリスト

出荷前に、小さな点が制約失敗を助けになる指示か行き詰まりにするかを決めます。

APIレスポンス：UIが実際に動けるか？

各バリデーション的失敗が特定の入力を指せる構造を返しているか確認してください。各エラーに field、安定した code、人間向けの message を返しましょう。一般的なデータベースケース（unique、foreign key、NOT NULL、check）をカバーし、技術的な詳細はログに残します。

UIの挙動：人が回復できるか？

完璧なメッセージでも、フォームがユーザーと戦うようでは意味がありません。最初の失敗フィールドにフォーカスしてスクロールし、ユーザーが既に入力した内容を保持します（特に複数フィールドのエラー時）。エラーはまずフィールドレベルで示し、要約は短くするか役立つときのみ表示します。

ログとテスト：回帰を検出できるか？

制約処理はスキーマ変更で静かに壊れるので、メンテされる機能として扱ってください。DBエラーは内部にログ（制約名、テーブル、操作、リクエストID）として残し、決して直接表示しないでください。制約タイプごとに少なくとも1つのテストを追加し、データベースの文言が変わってもマッピングが安定していることを確認します。

次のステップ：アプリ全体で一貫性を持たせる

多くのチームは1画面ずつ制約エラーを直します。それは助けになりますが、ギャップは残ります：あるフォームは明確なメッセージを出すが、別のフォームはまだ「リクエストが失敗しました」と言う。ユーザーはその差に気づきます。一貫性がパッチをパターンへと変えます。

痛い箇所から始めましょう。1週間分のログやサポートチケットを取り、頻出する制約を洗い出します。まずはその「上位の問題」からフレンドリーなフィールドメッセージを作るべきです。

エラー翻訳を小さなプロダクト機能として扱ってください。アプリ全体で使う共有マッピングを用意します：制約名（またはコード） -> フィールド名 -> メッセージ -> 回復ヒント。メッセージは平易に、ヒントは実行可能にします。

忙しいプロダクトサイクルに合う軽量なローアウトプラン：

• ユーザーが頻繁に遭遇する上位5つの制約を特定し、表示する正確なメッセージを作る。
• マッピングテーブルを追加し、データ保存を行うすべてのエンドポイントで使う。
• フォームがエラーをレンダリングする方法を標準化する（位置、口調、フォーカス動作）。
• 非技術メンバーとメッセージをレビューし「次に何をする？」と尋ねる。
• 各フォームに対して少なくとも1つのテストを追加し、正しいフィールドがハイライトされ、メッセージが読みやすいことを確認する。

手作業で全画面を書かなくても一貫した挙動を作りたいなら、AppMaster（appmaster.io）はバックエンドAPIと生成されたWeb/ネイティブのモバイルアプリをサポートします。これによりクライアント間で一つの構造化されたエラー形式を再利用しやすくなり、データモデルが変わってもフィールドレベルのフィードバックが一貫します。

チーム向けに短い「エラーメッセージのスタイル」ノートも書いておくと良いでしょう。シンプルに：避ける言葉（データベース用語）と、各メッセージに必ず含めること（何が起きたか、次に何をすべきか）をまとめてください。