API 400 の role 未対応エラーを、システム指示を壊さず直す

role 'system' is not supported on this modelなどの400エラーは、送ったロールやその位置が、利用中のAPI・モデルの仕様に合っていないことを示します。まずエラー本文と、SDKやゲートウェイで変換した後のJSONを確認してください。systemを一括でuserやdeveloperへ置き換えると、エラーが消えても運営側の指示が弱まったり、会話の途中で追加したルールの適用時点が変わったりします。

初期指示なら、Anthropic Messagesではトップレベルのsystem、対応するOpenAI Chat Completionsではsystemまたはdeveloper、Responsesではinstructionsなど、その接続先で認められた指示欄へ置きます。会話中のsystemとツール結果は別に確認します。Anthropicの一部の現行モデルは途中のsystemにも対応していますが、モデルと挿入位置に条件があります。

直ったかどうかは、元の接続先でリクエストが受理されることに加え、指示どおりの応答、ツールの呼び出しと結果の受け渡し、アプリの最終出力まで確認します。別のモデルで成功しただけでは、元の経路が復旧したことにはなりません。以下は2026年10月6日に確認した公式仕様にもとづく例です。掲載JSONの構文はローカルで確認していますが、実際のAPI呼び出しによる復旧テストは行っていません。

エラー本文を読んでからコードを変える

最初に保存するのはHTTPステータス、エラーのtype・code・message、返っていればparamとrequest IDです。paramがmessages[0].roleなら先頭の指示、別の番号なら履歴や追加メッセージを照合します。Anthropicなどではparamがなく、自然文とrequest IDだけが手がかりになることもあります。存在しない項目を待つ必要はありません。

たとえばアプリがuserしか渡していなくても、エージェントの既定プロンプトやメモリー処理がsystemを追加する場合があります。アプリに渡したオブジェクトだけでなく、HTTP送信直前の構造を見ます。ゲートウェイが上流へ再変換するなら、その変換後の構造も確認対象です。

診断用ログは、接続先とパス、モデルまたはdeployment名、APIバージョン、クライアント・変換処理のバージョン、各メッセージの番号・ロール・内容ブロックの種類に絞ります。本文、非公開の指示、ツール結果、APIキー、認証ヘッダーを丸ごと記録する必要はありません。ツールIDの対応は、同じIDを同じ仮名へ置き換えて示せます。

同じJSONを繰り返し送っても、未対応ロールの形式は変わりません。キーの再発行やリトライ回数の増加より、拒否された項目と送信先の仕様を先に照合します。ただし、ロールのエラーが出たことだけから認証・課金・モデル権限のすべてが正常だと断定することもできません。

習慣ではなく、利用中のAPIで修正を選ぶ

同じモデル名が表示されていても、/v1/chat/completions、/v1/responses、/v1/messagesは同じリクエスト形式ではありません。「OpenAI互換」という表示だけでも、すべてのロールや新機能の対応までは分かりません。

下の例にあるyour-selected-modelは、失敗したリクエストと同じ、利用可能なモデルIDへ置き換えます。Azureではその接続先に必要なdeployment名を使います。各例はリクエスト本文の形を示したもので、認証やHTTP送信処理を含むSDKサンプルではありません。

Anthropic Messages：初期指示はトップレベルのsystemへ

POST /v1/messagesで、会話の先頭に置く運営側の指示は、messages[0]のrole: "system"ではなくトップレベルのsystemへ置きます。次の例では、日本語で回答するという初期ルールをユーザーの質問と分離しています。Messagesの基本構造

{
  "model": "your-selected-model",
  "max_tokens": 256,
  "system": "日本語で回答してください。判断に必要な条件が不足していれば確認してください。",
  "messages": [
    { "role": "user", "content": "このAPIエラーの確認順序を教えてください。" }
  ]
}

修正するのは、最初から適用すべき指示を先頭のメッセージへ誤変換した箇所です。元の初期指示をトップレベルへ移し、残りの会話を順序どおり残します。既にトップレベルに指示があるなら、上書きで消さず、両方の内容と優先関係を確かめて統合します。画像などのデータブロックや、途中から適用する指示まで一緒に移してはいけません。

AnthropicのネイティブAPIにOpenAIのdeveloperやinstructionsをそのまま渡す修正も適切ではありません。アダプターがOpenAI形式を受け取りAnthropic形式へ変換する構成なら、そのアダプターの初期指示の変換を直します。

Anthropicの途中のsystem：モデルと挿入位置を確認する

現行のAnthropic APIは、指定されたモデルで会話中のrole: "system"を受け付けます。2026年10月6日の対応一覧にはFable 5.1、Mythos 5.1、Fable 5、Mythos 5、Opus 5.5・4.8・5、Sonnet 5.5があり、Sonnet 5は対象外です。Claude API、Bedrock、Google Cloudでの対応が記載されていますが、第三者ゲートウェイまで同じ機能を持つとは限りません。通常の途中のテキスト指示にベータヘッダーは不要です。途中のsystemの対応モデルと条件

対応モデルでも、位置は自由ではありません。

• 通常のuser、ツール結果を含むuser、またはサーバーツール結果で終わるassistantの直後に置きます。
• その次はassistantか配列の末尾にします。連続したsystemはひとまとまりとして位置を判定します。
• 配列の先頭や、assistantのツール呼び出しとuserの結果の間には入れません。

次は対応モデル向けの配置例です。初期指示を保持し、途中で追加した運営側の指示は最後に残しています。会話を再送するときも、以前のメッセージは元の順序で保持します。

{
  "model": "your-selected-model",
  "max_tokens": 256,
  "system": "日本語で回答してください。",
  "messages": [
    { "role": "user", "content": "障害の確認を始めます。" },
    { "role": "assistant", "content": "エラー本文と送信先を確認します。" },
    { "role": "user", "content": "次の応答で確認事項を挙げてください。" },
    { "role": "system", "content": "以後、確認事項は番号付きで回答してください。" }
  ]
}

途中の運営側の指示は、以後のターンへ同じ指示階層で適用され、後から追加した指示が優先されます。これをすべて最初のsystemへ集めると、ルールを適用する時点が変わります。userへ落とすと指示階層が変わります。外部サイトの文章やユーザーの入力、ツール結果は運営側の指示ではないので、この欄へ昇格させません。

なお、Messages APIリファレンスには、入力のsystemロールがないという旧説明と、systemを含む列挙が併存しています。途中のsystemについては、対応モデルと位置を明示した上記の専用ガイドを参照してください。古いSDKの型定義やゲートウェイの検査が新仕様に追いついていない場合もあるため、APIの対応と変換処理の対応を別々に確認します。

未対応の経路で途中の運営指示を保持する必要があるなら、その機能を扱えるアダプターや経路が必要です。同じ経路で安全に表現できる欄が見つからない状態を、単なるロール名の置換で「復旧済み」にしないでください。過去のthinkingブロックや署名、ツール履歴を削って通す方法も避けます。履歴の書き換えは、現行モデルのthinking検証にも影響します。履歴と制限の説明

OpenAI Chat Completions：モデルが受け付ける指示ロールを使う

POST /v1/chat/completionsではmessagesを使います。現行リファレンスはsystemとdeveloperを区別し、o1以降など新しいモデルではdeveloperが従来のsystem指示に相当すると説明しています。実際に使うモデルと経路がdeveloperを受け付けるなら、先頭の運営指示を次の形で送れます。Chat Completionsのメッセージ仕様

{
  "model": "your-selected-model",
  "messages": [
    { "role": "developer", "content": "日本語で回答し、未確認の原因を断定しないでください。" },
    { "role": "user", "content": "このAPIエラーの確認順序を教えてください。" }
  ]
}

developerはユーザーの指示より優先されます。ただし、公式APIで定義されていることだけを理由に、互換ゲートウェイやすべての旧モデルで受け付けるとは判断できません。developerが拒否されるなら、送信先のモデル仕様、上流API、アダプターが設定した形式を確認します。systemへの変換は、その経路が対応し、元の指示の役割を保てる場合に限ります。指示の優先順位

OpenAI Responses：instructionsは継続リクエストにも送る

POST /v1/responsesでは、運営側の指示をinstructions、今回のユーザー入力をinputへ置けます。

{
  "model": "your-selected-model",
  "instructions": "日本語で回答し、未確認の原因を断定しないでください。",
  "input": "このAPIエラーの確認順序を教えてください。"
}

previous_response_idで前回の応答を参照しても、前回のinstructionsは次のリクエストに引き継がれません。必要な運営指示は次のリクエストにも送ります。messagesをinputへ単純に改名するだけでは、ツールやreasoningを含む会話の移行は完了しません。対応する入力アイテムを保ちます。Responsesへの移行、instructionsの適用範囲

{
  "model": "your-selected-model",
  "previous_response_id": "resp_REPLACE_WITH_ACTUAL_ID",
  "instructions": "日本語で回答し、未確認の原因を断定しないでください。",
  "input": "その確認結果をもとに、次の手順を教えてください。"
}

Chat CompletionsからResponsesへの変更はAPIの移行です。新しいAPIで通ったことと、元のChat Completionsのエラーを直したことは分けて記録します。

Azure：現行のsystem対応を古い情報で否定しない

Azureの現行推論モデル向けガイドは、developerに加えてsystemにも対応すると説明しています。一覧にあるo4-mini、o3、o3-mini、o1では、systemメッセージをdeveloperメッセージとして扱います。一方、このガイドでは同じリクエストでsystemとdeveloperを併用しないよう案内しています。Azureの推論モデルとメッセージ対応

まず、実際のdeployment、モデルのバージョン、APIのパスとapi-versionの有無を確認します。現行のopenai/v1の例を、旧バージョンの別deploymentへ無条件に当てはめないでください。「Azureではsystemが使えない」「旧APIならdeveloperはすべて使えない」と一括で決めず、対象の仕様に合わせて一つの指示ロールを選びます。

toolやfunctionのエラーは、呼び出しと結果を組で直す

ツール結果は運営側の指示ではありません。toolが拒否されたからといって、本文をsystemへ移すと、外部データを高い優先度の指示として扱う危険があります。必要なのは、呼び出しと結果の形式、識別子、順序を合わせることです。

以下は履歴内の対応関係を示すJSON断片です。リクエスト全体ではなく、ツール定義、モデル、初期入力などは省略しています。call_demoとtoolu_demoは説明用のIDで、実際にはAPIが返したIDを使います。

Chat Completionsはtool_call_idで対応させる

assistantのtool_calls[].idと、結果メッセージのtool_call_idを一致させます。旧functionメッセージをtoolへ改名するだけでは、この対応は作れません。OpenAIのtoolメッセージ仕様

[
  {
    "role": "assistant",
    "tool_calls": [
      {
        "id": "call_demo",
        "type": "function",
        "function": { "name": "lookup_status", "arguments": "{}" }
      }
    ]
  },
  { "role": "tool", "tool_call_id": "call_demo", "content": "正常" }
]

Responsesはfunction_call_outputを返す

Responsesではツール結果はrole: "tool"のメッセージではなく、type: "function_call_output"の入力アイテムです。対応するfunction_callのcall_idを返します。手動で履歴を管理する場合は、必要なreasoningやfunction callのアイテムも残します。下は対応する二つのアイテムだけを示しています。メッセージからアイテムへの移行

[
  {
    "type": "function_call",
    "call_id": "call_demo",
    "name": "lookup_status",
    "arguments": "{}"
  },
  { "type": "function_call_output", "call_id": "call_demo", "output": "正常" }
]

Anthropicはuser内のtool_resultを使う

Anthropicのクライアントツールでは、assistantのtool_useに対し、直後のuserにtool_resultを入れます。tool_use_idは呼び出しのidに合わせます。複数の結果を返すときはすべての結果ブロックをテキストより前に並べ、呼び出しと結果の間にsystem指示を挟みません。Anthropicのツール結果と順序

[
  {
    "role": "assistant",
    "content": [
      { "type": "tool_use", "id": "toolu_demo", "name": "lookup_status", "input": {} }
    ]
  },
  {
    "role": "user",
    "content": [
      { "type": "tool_result", "tool_use_id": "toolu_demo", "content": "正常" }
    ]
  }
]

サーバーツールには別の継続条件があります。未完了のサーバーツール呼び出しを引き継ぐ場面では、公式ガイドが指定するtool_resultだけのuserメッセージや、必要なツール定義の保持を確認します。クライアントツールの例をそのまま適用せず、元のツール種別に合わせます。

このように、三つのAPIで異なるのはロール名だけではありません。変換処理では、IDの対応、結果のブロック形状、会話の順序をひとまとまりで扱います。履歴を全部消して短い会話にすれば受理されても、ツールを使った元のタスクは復旧していません。

フレームワーク更新後に発生したときの切り分け

更新後だけ400が出るなら、更新前後で変わった送信形式を比較します。具体的には、初期指示の位置、会話中の追加指示、ロールの列挙、ツール結果の変換、追加機能のフィールドです。フレームワークへ渡す前の配列が同じでも、送信直前のJSONが同じとは限りません。

Claude Codeには2026年5月の未対応systemエラーの報告がありますが、報告者ごとにクライアント、モデル、接続先が異なります。特定バージョンへの変更で通ったという報告を、現在のすべての環境に効く修正として扱わないでください。

現行のClaude Codeエラー説明では、systemの位置を指定するエラーと、クライアントの最低バージョンに関するエラーを区別しています。途中のリマインダー等に対する一度のuser形式への再送というクライアント処理も、初期system指示をすべてuserへ移す方法とは別です。エラー文が違うなら、同じ原因や修正だと決めつけず、実際に送信したクライアントのバージョンと対象機能を確認します。

接続先の選択や認証方式から確認し直す必要がある場合は、Claude CodeのAPI設定とゲートウェイの確認手順を参照してください。認証設定が合っていることと、モデルがそのリクエスト形式を受け付けることは別の確認です。

同じ接続先で、受理から最終出力まで確かめる

比較するときは、provider、base URLとパス、APIバージョン、モデルまたはdeployment、SDK・フレームワーク・アダプターを固定します。モデル変更、API変更、フレームワークの除去を同時に行うと、どの修正が効いたか分かりません。

1. 元の構造を把握する。 秘密情報を除き、拒否されたロールと位置、前後の種類を保存します。
2. 一つの修正を加える。 たとえば初期指示だけをトップレベルへ移します。途中の指示やツール履歴は別に扱います。
3. まずローカルで構文と対応関係を確認する。 JSONとして読めるか、ロールの綴りや必須フィールド、ツールIDの組が合うかを見ます。全API共通の固定ロール一覧ではなく、確認済みの接続先の仕様を使います。
4. 承認済みの環境で同じ接続先へ送る。 ロールエラーが消えたかを確認します。別の400に変わっただけなら、新しいエラー項目の確認へ進みます。
5. 指示の挙動を確認する。 日本語指定や出力形式など元の運営ルールと、それに反するユーザー入力を含む確認用ケースを使い、必要な制御が保たれるかを見ます。一度の応答であらゆる状況の優先度を保証できるわけではありません。
6. 元のアプリで会話を続ける。 ツールが必要なら呼び出し、結果の返送、その結果を使った応答まで通し、期待した最終データがアプリへ届くことを確かめます。

たとえばJSON出力が必要なアプリでは、応答を受け取るだけでなく、期待するスキーマで解析できることが完了条件です。ツールを使う処理なら、結果を返すところで止めず、その結果を使って最終回答を作るところまで確かめます。

まだ同じエラーが残る場合は、接続先、モデル、バージョン、エラー本文、request ID、秘密情報を除いた構造、試した変更をまとめると、ゲートウェイやアダプターの担当者が切り分けやすくなります。非公開の指示や顧客データの全文を含める必要はありません。

よくある質問

systemをすべてdeveloperに変えれば直りますか？

一律には直りません。対応するOpenAI Chat Completionsなら選択肢になりますが、Anthropicの初期指示はトップレベルのsystem、Responsesではinstructionsなど形式が異なります。Azureの現行ガイドはsystemにも対応し、systemとdeveloperの併用を避けるよう案内しています。実際のモデルとAPIに合わせてください。OpenAIの仕様、Azureの仕様

Anthropicのmessagesにはsystemを絶対に入れられませんか？

初期指示はトップレベルに置きます。一方、現行の指定モデルでは、位置の条件を満たす途中のsystemメッセージを使えます。先頭やツール呼び出しと結果の間には置けません。第三者ゲートウェイや古いSDKの対応も確認してください。途中のsystemの条件

systemをuserに入れて400が消えたら成功ですか？

リクエスト形式が通っただけでは成功とはいえません。userへ移すと運営指示の優先度が変わり、ユーザー入力との関係も変わります。対応する指示欄か変換処理で元の役割を保ち、出力とツール往復を確認します。外部データをsystemへ移して逆に優先させる方法も避けます。指示の優先順位

Responsesで前回のinstructionsを書き直す必要はありますか？

previous_response_idを使って継続する場合、前回のinstructionsは引き継がれません。今回も必要な指示は明示して送ります。会話が続いていることと、前回の指示が残ることを同一視しないでください。instructionsの説明

「最後はuserで終える」というエラーも同じ原因ですか？

同じとは限りません。たとえば現行のGemini 3.8 Flash移行ガイドは、末尾の事前入力したmodelターンを除き、空でないテキストを持つuserターンで終えるよう説明しています。これはsystemロールの未対応とは別の条件です。過去のmodelメッセージを全部userへ変える方法ではなく、実際の対象モデルの末尾条件を直します。Geminiの移行条件

ほかの400も同じロール修正で直せますか？

400だけでは原因を特定できません。未対応の事前入力、画像、出力スキーマ、追加機能のフィールドなどは別の検査です。エラーが指す項目を読んで切り分けます。ロールの問題を直すために、必要な機能や会話履歴を無差別に削らないでください。