こんにちはCLBです。
転職してからと言うもの、とあるシステムのバックエンドとして
ひたすらAPIを作る仕事をしています。
そんな時にエラーではまった話を書いて行きます。

当初の設計

こんな風にAPIのエラーを返却していました。

{
    "error-message" : "〇〇が入力されていません"
}

そして、〇〇が入力されていません と言う文章をそのままフロントエンドの画面に表示していました。
この時の自分にとっては、特に問題はなさそうに見えました。
「こんなもんなんだ。」程度にしか理解していませんでした。

問題発生

フロントエンダーの方がこんなバグを見つけます。

エラーメッセージが正しく無い。
〇〇ではなく、 △△であるべきだ。

確かに画面を見てみると 〇〇 ではなく、 △△ と言う項目名が利用されていました。
この時自分は、「汎用のエラーメッセージを利用していたのが間違いだったなぁ」と思い、修正に取り掛かろうとしました。
しかし、フロントエンドの方はこうも付け加えました。

このエラーメッセージの項目はフロントエンド画面の状態によって
△△ ではなく、 ×× となる場合がある。
フロントから現在の画面の状態を送るので、それを元にエラーメッセージの項目名を変更してほしい。

パニックが始まりました。

どうなったか

話し合いの結果、フロントエンド画面は状態によって項目の名前が変わる仕様が無くなり、
自分は項目名の修正を行うことで落ち着きました。
これによって画面に表示される項目と、APIのエラーメッセージに差異がある問題はなくなったものの、
依然としてエラーメッセージを組み立てる際にフロントエンドの画面がどうなるかを意識する必要は残り続けました。

どうすべきだったか

この設計の問題点はバックエンド側がエラーコード等の状態ではなく、
メッセージをそのまま返却しており、その内容は画面を考慮しないといけないと言うのが
今回の事態の原因だと感じました。

なので、今回のような事を防ぐ為には

バックエンドはエラーコードを返却する
フロントエンドはエラーコードを元に画面に表示するメッセージを組み立てる

と言った風にするのが理想だと思いました。
(もちろん、フロントエンドの方の作業が増えてしまうのですが・・・)

バックエンドとしては GitHub APIのような以下の形がいいなぁと思いました。

{
  "message": "Validation Failed",
  "errors": [
    {
      "resource": "Issue",
      "field": "title",
      "code": "missing_field"
    }
  ]
}