REST API が success: true を返すのに値が変わらないときの切り分け手順

外部 API（PMS・チャネルマネージャー・SaaS 管理系・在庫や価格を扱う業務 API）へ書き込みを投げ、 HTTP 200/201 と success: true が返ったのに、読み戻すと1つも変わっていない——という状況を 最短で切り分けるための指示書。AI エージェントにそのまま読ませて実行させる粒度で書いてある。

この失敗は「エラーが出ない」ため最も危険で、成功レスポンスを根拠に完了報告すると嘘の報告になる。 実際にこれを踏み、12エントリすべてに success: true が返ったまま何も変わっていない状態を 「反映済み」と報告しかけた。読み戻しで気づいた。

---

大原則

success: true は「リクエストが受理された」であって「値が変わった」ではない。 判定に使ってよいのは次の2つだけ:

1. レスポンスに何を変えたかのエコーが含まれているか（modified / updated / changed など）
2. 読み戻した実値

---

手順

1. レスポンスの差分エコーを見る

多くの API は「実際に変更したフィールド」をエコーする。書けた場合と無視された場合で キーの有無が変わるので、これが最速の判定材料になる。

# 効いた場合
[{"success": true, "modified": {"id": <ID>, "items": [{"from": "...", "minStay": 2}]}}]

# 無視された場合（同じ 201 / 同じ success:true）
[{"success": true}]

エコーが無い API なら手順2へ。レスポンス長やステータスコードでは絶対に判定しない。

2. 「書ける項目」を道連れに送って、行ごとか項目ごとかを切り分ける

同じレコード（同じ ID・同じ日付・同じキー）に対して、確実に書けると分かっている別の項目を 一緒に、あるいは単独で送る。

# 疑っている項目
{"id": <ID>, "items": [{"key": "<KEY>", "targetField": <VALUE>}]}
# 確実に書ける項目（比較対象）
{"id": <ID>, "items": [{"key": "<KEY>", "knownWritableField": <VALUE>}]}

• 比較対象が書けた → 「このレコードが書けない」のではなく「この項目だけ書けない」。手順4へ。
• 比較対象も書けない → レコード単位の問題（権限・スコープ・ロック・別の所有者）。手順3へ。

比較対象には元の値に戻せる項目を選ぶこと。値を控えてから変更し、判定できたら即戻す。

3. 権限とスコープを確認する（推測で騒ぐ前に1コール）

トークンのスコープを返すエンドポイントがあれば読む（例: GET /authentication/details）。 書き込みスコープが無ければ普通は 401/403 になるが、サイレントに無視する実装もあるため確認する。

権限が足りているなら、書き込み拒否は仕様側の理由。手順4へ。

4. 「その項目は読み取り専用の計算値」を疑う

いちばん多い真因がこれ。その値が他の入力から算出されている場合、代入は黙って捨てられる。

チェックすること:

• 項目名の総当たりで時間を溶かさない。 候補名を10個試して全部無視されるなら、 名前の問題ではなく書き込み不可である可能性が高い。手順1のエコーがあるなら、 総当たりは1回のリクエストにまとめて「どの名前がエコーに出るか」で一括判定できる。

• 設定オブジェクトを読んで、依存関係・連動・数式・派生の定義を探す。 リソース設定の取得エンドポイント（GET /resources?include...=true）に dependencies / linked / formula / derived / combinationLogic のような項目がないか見る。

• 見つかったら「計算の入力」を書く。 出力は書けなくても入力は書けることが多い。

  実例: 在庫数が「他リソースとの依存関係から算出される計算値」だったため、 各リソースの在庫数への代入は全部無視された。一方、上位リソースに置かれていた 手動ブロック（override）は書けた。それを外した1リクエストで、依存関係を通って 全リソースの在庫が一斉に開いた。出力を12回叩くのではなく、入力を1回叩くのが正解だった。

• 「その値を実際に持っているレコード」に書く。 派生側に書いても効かない。 ここを間違えると「この項目は書けない」と誤った結論を残す（実際に誤記した）。

5. UI 側の同等機能を探す（API に無いことがある）

API で書けないなら、管理画面には別名の項目として存在することが多い（同じ概念に別の UI ラベルが 付いている）。ベンダーのマニュアルや社内の運用手順書にその画面操作が書かれていないか探す。 運用手順書は「API に無い操作」の在処を知っている一次情報になる。

6. 読み戻しで完了判定する（例外なし）

書き込み → 差分エコーを確認 → 実値を読み戻す → 外向きの表示を確認

• 読み戻しは期待値との一致を exit code で機械判定する。目視の「だいたい合ってる」を挟まない。
• 値を変えた範囲の外側も1回読む（範囲指定を間違えていても内側だけ見ると気づけない）。
• 顧客・利用者に見える画面があるならその画面を開いて読む。API の値と表示は日常的にズレる。 「新しい値が出ている」と「古い値が消えている」を必ずセットで確認する。

---

やってはいけないこと

やりがち	なぜ駄目か
success: true を根拠に完了報告	本稿の全内容がこの反例
レスポンス長・ステータスコードで判定	無視された場合と同じになる
項目名の総当たりを延々続ける	名前の問題ではなく書き込み不可のことが多い。エコーで1回にまとめる
派生側のレコードで「書けない」と結論	値の所有者に書けば通る。誤った知識が残る
一括投入をいきなり全範囲に流す	まず1件で試して読み戻す。全範囲は原因が確定してから
比較対象の項目を戻さず放置	切り分けのために変えた値は必ず元に戻し、戻したことも読み戻す

再利用できるチェックリスト

• レスポンスに差分エコーがあるか確認した
• 書ける項目を道連れに送り、行単位か項目単位かを切り分けた（変えた値は戻した）
• トークンのスコープを確認した
• 設定オブジェクトで依存関係・連動・数式の定義を探した
• 「値の所有者」のレコードに書いた
• API で無理なら UI 側の同等機能を探した
• 1件で試し、読み戻してから全範囲に広げた
• 実値の読み戻しを exit code で機械判定した
• 変更範囲の外側も1回読んだ
• 利用者に見える画面を開いて確認した（新値が出ている／旧値が消えている）