Citationsとstructured outputsが併用できない理由と400エラー条件

同じリクエストに入れると400になる組み合わせ

Claude APIのCitationsとstructured outputsは、同じリクエストに入れると400エラーでリクエストごと拒否される組み合わせです。条件は2つです。

• documentブロックまたはsearch_resultブロックでcitations.enabled: trueを指定している
• 同じリクエストにoutput_config.format(旧output_formatを含む)がある

どちらか一方だけなら問題なく動きます。RAG(検索拡張生成)で検索結果をsearch_resultブロックとして渡している実装も、ドキュメントを直接渡す実装も条件は同じで、判定に使われるのは「Citations有効なブロックの有無」です(ドキュメント種別ごとの引用形式の違いはClaudeのCitationsは引用形式がPDF・テキスト・カスタムで変わるで扱っています)。

structured outputsは、JSON outputs(output_config.format)とStrict tool use(strict: true)の総称です(Claude JSONモードの使い方で基本を解説しています)。400の条件として名指しされているのはoutput_config.format(JSON outputs)で、strict tool useとの組み合わせは条件に入っていません。

# citationsとoutput_config.formatを同居させると400になる例
curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 1024,
    "messages": [{
      "role": "user",
      "content": [
        {
          "type": "document",
          "source": {"type": "text", "media_type": "text/plain", "data": "..."},
          "citations": {"enabled": true}
        },
        {"type": "text", "text": "この内容をJSONで要約して"}
      ]
    }],
    "output_config": {
      "format": {"type": "json_schema", "schema": {"type": "object", "properties": {"summary": {"type": "string"}}}}
    }
  }'

返ってくるのは共通のエラー形式で、error.typeはinvalid_request_error、レスポンスには追跡用のrequest_idも入ります。

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "..."
  },
  "request_id": "req_..."
}

400の原因がCitationsかどうかを切り分ける

output_config.formatを付けたリクエストが400で落ちたとき、原因の候補は3つあります。切り分けは次の順に進めると1往復ずつで絞れます。

スキーマ由来の400は、スキーマ自体を直さない限り残ります。なお、Citationsが対応するのはテキストの引用だけで、画像の引用はまだできません。エラーハンドリングの実装パターン全般はClaude APIのエラーハンドリング設計にまとめています。

なぜ両立しないのか

Citationsが有効なとき、引用付きブロックは、cited_textと文書内の位置を持つcitations配列を抱えて、文章の途中に割り込みます。

Anthropicの説明は、引用の割り込みと厳密なJSON Schemaの制約がぶつかる、という一点です。

グラマーの適用範囲も、この非互換を読む手がかりになります。グラマーがかかるのはClaudeの直接テキスト出力だけで、ツール呼び出し・ツール結果・thinkingタグには及びません。セクションが切り替わるたびにグラマーの状態もリセットされるので、Claudeは自由に考えてから最後だけ構造化して答えられます。

JSON outputsで注意したいのは、400にならないのにスキーマへ合わない出力が返る場合です。次の2つが該当します。

• 拒否(stop_reason: "refusal")は、ステータス200で返ります
• max_tokensに達した場合(stop_reason: "max_tokens")は、出力が途中で切れてスキーマに合わないことがあります

文字列のenumとconstは、大文字小文字までは保証されません。2段目の出力を受ける側では、stop_reasonの確認と値の正規化が要ります。

併用できる機能とできない機能

structured outputs側の互換性欄には、併用できるものと併用できないものがはっきり分かれて載っています。

Citationsの側から見ると、併用可能な機能はプロンプトキャッシュ・トークンカウント・バッチ処理です。非互換として両方のページに載っているのはJSON outputsです。Citationsとstrict tool useを同じ会話に入れたい設計では、先に両方だけの小さいリクエストで挙動を確かめてから組み込むという手があります。

prefillはClaude 4.6以降のモデルでは最後のassistantターンへの指定自体が400になります。経緯はClaude 4.6でprefillが廃止された理由と5つの移行先にあります。

併用したいときは2回に分ける

根拠付きの回答と機械可読なデータの両方が要る用途では、リクエストを分けます。社内ナレッジを参照して答えつつ、同じ内容をそのままチケット管理システムに渡せる形でも欲しい、といったエージェントが典型です。

この構成には設計上の判断が2つ付きます。

1つ目は、2回目に渡す引用の形です。1回目が返したcited_textをそのまま埋め込む案と、必要な部分だけ抜粋し直す案があり、先に決めておくと実装がぶれません。cited_textはCitationsの応答では出力トークンに数えられません。citationsブロックのまま次のターンへ返す場合は入力トークンにも数えられませんが、2回目の入力に文字列として埋め込めば通常の入力トークンとして数えられます。Citationsを有効にすると、システムプロンプトの追加とドキュメントの分割で入力トークンがわずかに増える点も、1回目のコストに入ります。仕組みはClaude Citationsのトークンコストの仕組みで扱っています。

2つ目は、プロンプトキャッシュです。output_config.formatを変えると、その会話スレッドのプロンプトキャッシュは無効になります。さらにstructured outputsを使うと、出力形式を説明する追加のシステムプロンプトがClaude側で自動的に入り、入力トークンがわずかに増えます。2段構成では、formatを付ける2回目と、付けない1回目でキャッシュの扱いが別々になる点も設計に入れておきます。

1回目のキャッシュは、元ドキュメントの側で効かせます。応答に含まれるcitationsブロックは直接キャッシュできませんが、参照先のドキュメントはキャッシュできます。トップレベルのドキュメントブロックにcache_controlを付けます。

グラマーにも別のキャッシュがあります。同じスキーマを初めて使うときはグラマーのコンパイルで遅延が増え、コンパイル済みのグラマーは最後に使ってから24時間保持されます。nameやdescriptionだけの変更ではこのキャッシュは無効になりません。プロンプトキャッシュとは別物で、2段目を同じスキーマで繰り返す運用では2回目以降の遅延が下がります。

2回目のスキーマに持ち回る引用フィールド

2段目でJSON化するとき、引用の位置情報をスキーマのプロパティとして受け取りたい場合があります。位置情報の形はドキュメントの種類で決まり、1回目の応答にはその形のまま入っています。

どの型でもdocument_indexとdocument_title、引用された原文のcited_textが付きます。document_indexはリクエスト内の全メッセージにまたがるドキュメントブロックの並びに対する0始まりの番号なので、2回目にドキュメントを再送しない構成では、番号が何を指していたかを自前の対応表で持っておく必要があります。

もう1つ、位置情報の型がドキュメントごとに違うため、スキーマを1つに固定するなら、型ごとにanyOfで分けるか、共通部分(document_index・cited_text)だけを持たせるかを選ぶことになります。anyOfは対応していますが、anyOfや型の配列を使うパラメータは1リクエストで16個まで、オプションのパラメータ(requiredに無いもの)は全スキーマ合計で24個までです。上限を超えると、前述の「Schema is too complex for compilation」で400になります。明示された上限をすべて満たしていても、コンパイル結果が大きすぎると180秒のタイムアウトに当たることがあります。

対処は、可能なパラメータをrequiredにしてオプションを減らすことです。オプションのパラメータ1つごとに、グラマーの状態空間が部分的におよそ2倍になるためです。それでも収まらなければ、スキーマを分けて複数リクエストにします。共通部分だけに絞る案も、この上限に当たりにくい選択肢です。

まとめ

2段構成で後から困りやすいのは、1回目のdocument_indexが指していたドキュメントの対応表を残さないことと、2段目のスキーマを位置情報の型ごとに広げすぎることです。対応表を自前で持ち、スキーマは共通部分から始めておけば、この制約は運用で吸収できます。