Agent Voice: AIエージェントが諦めるエラーメッセージTOP6 — 「400 Bad Request」だけ返すAPIに失われるトークンと信頼 2026

エラーメッセージは2026年APIの「隠れたUI」

2025年まで、APIのエラーメッセージは「人間の開発者が読むもの」だった。Slackで質問する、ドキュメントを開く、Stack Overflowを検索する——詰まったときの逃げ道が複数あった。

2026年、状況は反転した。APIの一次的な利用者は人間ではなくAIエージェントになり、エージェントは『ググる』『同僚に聞く』ができない。エラーレスポンスだけが、エージェントにとって 復帰のための唯一の手がかり だ。

業界レポートでは、ある開発チームが 「422レスポンスを本文なしで返すAPIに対し、エージェントが永久ループでリトライした」 という事例を報告している。本文に "missing required field 'first_name'" を明示しただけで、エージェントは即座に修正して成功した。エラーメッセージは2026年APIの隠れたUIであり、UX投資の対象だ。

KanseiLink実測 — エージェントが詰まるエラーの実態

KanseiLinkがMCP経由で収集している実エージェント挙動データから、エラー周りの数字を抜き出すと以下の傾向が見える。

注目すべきは 「api_error」の中身が示されていない 点だ。429・422・404・500を一括して『api_error』として扱う実装が多く、エージェントは「自分が悪いのか、サーバーが悪いのか、リトライすべきか」を判別できない。一方 auth_expired には 「OAuthトークンを更新した(24h期限)」という再現性のある対処 が登録されているため、エージェントは次回同じエラーに遭遇しても自動復帰できる。

この対比は、「エラータイプの粒度」と「対処方法の明示」が成功率を決めるという、本記事のコアメッセージそのものだ。

アンチパターンTOP6

KanseiLinkが収集した実測データと業界調査から、AIエージェントを困らせるエラーメッセージの典型6パターンを抽出した。

❌ 1位: 本文なしの4xx

「422 Unprocessable Entity」だけ返してbodyが空、あるいは「{"error": "validation failed"}」とだけ書かれているケース。エージェントは「何のフィールドが、どの理由で失敗したか」を判別できず、同じリクエストを永久にリトライしてトークンを浪費する。業界で報告されている「missing required field 'first_name'」を明示するだけで解消した事例が示すとおり、フィールド名の明示が最低条件だ。

❌ 2位: エラーコードが粒度不足

{"error": "api_error"} や {"code": "ERR_001"} のような、機械的に判別できない汎用コード。KanseiLinkで観測されたfreeeの15件 api_error がまさにこれで、内訳が分からないため運用側の改善着手点も曖昧になる。エラーコードは「次にエージェントが何をすべきか」を一意に決める識別子 であるべきで、amount_must_be_positive や quota_exceeded_for_period のように動詞・対象が明示された安定文字列が望ましい。

❌ 3位: retryableヒントの欠如

422(検証エラー)に対してエージェントが永遠にリトライする現象は、retryable: false 一行で防げる。逆に429・503などには retryable: true + retry_after_seconds を返すべきだ。このフィールド一つの追加で、エージェントの無駄なトークン消費が劇的に減ると業界では報告されている。設計コストと効果の比が極端に良いため、優先度の最も高い改善項目の一つだ。

❌ 4位: スタックトレース・内部実装の漏出

NullPointerException at com.example.UserService.findById:142 のような内部スタックトレースをそのまま返すAPI。セキュリティリスクであるだけでなく、エージェントは無関係な内部情報に注意を引かれ、本質を見誤る。「Cannot read property 'id' of undefined」のような実装側のJavaScriptエラーが、ユーザーに伝わるエラーメッセージとしてエージェント経由で表示される事故も実際に発生している。

❌ 5位: 言語・スキーマの混在

エラーフィールド名は英語("validation_error")だがメッセージは日本語混在、しかも文体が時々で変わる(です・ます調と命令形が混在)、というケース。エージェントは多言語を理解はするが、「machine-readableな部分」と「human/LLM-readableな部分」を分離していない構造では、機械的なswitch分岐が組みにくくなる。推奨は error.code と error.field は安定した英語、error.message と error.user_message は多言語対応、というハイブリッド。

❌ 6位: エラーenvelopeの不統一

同じAPIで認証エラーは {"err": "..."}、検証エラーは {"errors": [{"msg": "..."}]}、サーバーエラーはHTMLで返ってくる——というふうに、エンドポイント間でエラー形式がバラバラなケース。エージェントは 「全エンドポイントで共通のエラーパースロジック」を組めず、ツール毎に個別対応が必要になる。MCPサーバー実装でも、ラップする上流APIが不統一でも、MCP出口では必ず統一envelopeに正規化するのが2026年のベストプラクティスだ。

処方箋: LLM-friendly エラーenvelope

上記6パターンを全て吸収する、推奨されるエラーレスポンス構造は以下のとおり。フィールド名は業界での慣例を参考にしているが、固有のドメインに合わせて拡張可能だ。

{
  "error": {
    "code": "amount_must_be_positive",          // 機械可読・安定文字列
    "message": "The 'amount' field must be a positive integer. Received: -100.",
    "field": "amount",                          // 該当フィールド名
    "retryable": false,                         // 自動再試行で成功しうるか
    "suggested_fix": "Pass an integer >= 1 (in JPY).",
    "doc_url": "https://api.example.com/docs/errors#amount_must_be_positive",
    "request_id": "req_01HQ8K3...",            // サポート問い合わせ用
    "user_message": "金額は正の整数で入力してください"  // エンドユーザー向け(任意)
  }
}

認証期限切れ・レート制限など、特定カテゴリには追加フィールドが効く。

実装例 — Before/After

Before(エージェントが詰まるパターン)

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "error": "validation failed"
}

エージェント側挙動: 「何かが悪いがどこか分からない」→ 同じリクエストを再送 → 同じエラー → 数回の往復後にユーザーに「失敗しました」とだけ返す。10〜20回の無駄なリトライでトークンと時間を浪費。

After(エージェントが復帰可能なパターン)

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "error": {
    "code": "missing_required_field",
    "message": "Required field 'client_email' is missing in the request body.",
    "field": "client_email",
    "retryable": false,
    "suggested_fix": "Add 'client_email' as a string (RFC 5322 email format) to the request body.",
    "doc_url": "https://api.example.com/docs/invoices#create",
    "request_id": "req_01HQ8K3..."
  }
}

エージェント側挙動: 「client_emailが欠けている」を即座に解釈 → ユーザー入力からclient_emailを抽出 or 推測 → 1回の修正リトライで成功。所要時間とトークンが1/10以下に短縮。

SaaS提供側チェックリスト

あなたのAPIまたはMCPサーバーが「エージェントに優しい」かを確認する10項目。

• 4xxレスポンスは必ずJSONボディを返す(空ボディなし)
• error.code は安定した英語の機械可読文字列で、ドキュメント化されている
• error.field で該当フィールド名を明示している
• error.retryable でリトライ可否を boolean で示している
• error.suggested_fix でエージェントが取るべき次の行動を1〜2文で示している
• auth_expired には refresh_url または再認証フローへのヒントが含まれる
• rate_limited には retry_after_seconds と scope が含まれる
• 全エンドポイントで同じエラーenvelope構造に正規化されている
• スタックトレース・内部実装パスが本番レスポンスに漏れていない
• request_id がサポート連絡時の追跡用に含まれている

FAQ

Q1. なぜエラーメッセージの品質が2026年APIで重要なのか?

API利用者の主流が人間からエージェントに移った。エージェントは『ググる』『同僚に聞く』ができず、エラーレスポンスが復帰のための唯一の手がかり。曖昧なエラーは無意味なリトライとトークン浪費を生み、最終的にユーザー体験が崩壊する。

Q2. KanseiLinkで最も多いエラーは?

freee MCP(212レポート)では『api_error』が15件で最多、次いで『auth_expired』が4件。auth_expiredには再現性ある対処が登録され自動復帰可能だが、api_errorは内訳不明でエージェントが対処判断不能というのが典型的な対比。

Q3. retryableフィールド追加でなぜトークンが節約される?

エージェントはデフォルトで「失敗→再試行」しがちで、422のような再試行不可エラーにも繰り返し試みる。retryable: false の明示で即座に上位ロジックに切り替わり、無駄な往復が消える。業界では「retryable導入1週目でトークン消費が目に見えて下がった」報告がある。

Q4. 日本語エラーメッセージはエージェントに通じる?

意味は通じるが、機械判別の障害になる。推奨は『error.code・field名は英語、message・user_messageは多言語対応』のハイブリッド。switch分岐に使うコードと、人間/LLMが読む説明を分離するのが定石。

Q5. MCPサーバー側で実装すべき最低基準は?

5項目: (1)error.code(機械可読安定文字列)、(2)error.message(LLM可読1〜2文)、(3)error.field(該当フィールド)、(4)error.retryable(boolean)、(5)error.suggested_fix(修正例)。実装コスト小・成功率効果大の高ROI改善。

Q6. 古い上流APIをラップするMCPサーバーでも適用できる?

適用可能で、むしろMCPの主要価値。上流が不統一なエラーを返しても、MCP出口で必ず統一envelopeに正規化することで、エージェントから見た複雑性を吸収する。これが「MCPがAPIラッパー以上の価値を持つ」典型例の一つ。