6.3コントローラAPIとREST応答の解釈

コントローラAPIの自動化で最も時間を溶かすのは、返ってきたコードの意味を取り違えて、見当違いの場所を直そうとすることです。401が返っているのにURLを何度も書き換えたり、429が返っているのに即座に再試行してさらに詰まらせたり——いずれもコードが指している「責任の所在」を読めていないことが原因です。応答コードは大きく、2xx＝成功／4xx＝呼び出し側（クライアント）の問題／5xx＝サーバ側の問題という責任の切り分けを示します。この節ではCatalyst CenterとSD-WAN Managerという実際のコントローラを題材に、認証トークンの取得→呼び出し→応答の解釈→次の一手という一連の流れを追います。

6.3.1コントローラAPIの呼び出しの型

• Catalyst Center（旧DNA Center）は企業アクセス網を統制するオンプレのコントローラで、Intent APIを公開する。呼び出しはまずPOST /dna/system/api/v1/auth/tokenにBasic認証で資格情報を送ってトークンを取得し、以後は取得したトークンをX-Auth-Tokenヘッダに載せて/dna/intent/api/v1/network-deviceのような意図ベースのエンドポイントを呼ぶ。トークンには有効期限があり、期限切れ後の呼び出しは401になる。
• SD-WAN Manager（vManage）はWANオーバーレイの管理コントローラで、デバイス在庫・テンプレート・ポリシー・統計をRESTで扱う。認証後に/dataservice/deviceのようなエンドポイントを呼び、セッション（およびCSRF用トークン）を維持して操作する。どちらのコントローラでも「認証は別リクエストで、以降の呼び出しはヘッダで資格を提示する」型は共通である。
• HTTPメソッドは操作の種類を表す：GET＝取得（安全・状態を変えない）／POST＝作成（新しいリソースやジョブを起こす）／PUT＝置換（送らなかった項目は消えうる）／PATCH＝部分更新／DELETE＝削除。コントローラではPOSTが即座に完了せず「タスクID」を返す非同期処理になることがあり、その場合はタスク照会のエンドポイントをGETして完了を確認する必要がある。

6.3.2応答コードが示す「責任の所在」

• 2xx＝成功。200 OK＝要求が成功し本文（ペイロード）を伴う（GETの典型）。201 Created＝新しいリソースが作成された（POSTの典型で、作成先がLocationヘッダや本文で示される）。204 No Content＝成功したが返す本文が無い（DELETEや一部の更新の典型）——204を「失敗」と読んで再実行すると二重実行の事故になりうる。
• 4xx＝呼び出し側の問題なので、同じ内容で再試行しても直らない。400 Bad Request＝リクエストの形式や内容が不正（JSON構文エラー・必須項目の欠落・型不一致）→ペイロードを直す。401 Unauthorized＝認証されていない（トークン未提示・期限切れ・資格情報が誤り）→トークンを再取得する。403 Forbidden＝認証は通ったが権限が無い→アカウントのロール/権限を見直す（トークンを取り直しても同じ結果）。
• 404 Not Found＝指定したリソース（URL）が存在しない→エンドポイントのパスやリソースIDの綴りを確認する（401と違い資格情報の問題ではない）。429 Too Many Requests＝レート制限に達した→即座の再試行は禁物で、Retry-Afterヘッダがあればその秒数だけ待ち、指数バックオフで間隔を空けて再送する（並列度を下げる/バルク取得に変えるのも有効）。
• 5xx＝サーバ側の問題（500 Internal Server Error・502 Bad Gateway・503 Service Unavailable）で、リクエスト自体は正しい可能性が高い。したがってペイロードやトークンを書き換えるのは的外れで、バックオフを入れた再試行とコントローラ側のログ/状態確認が正しい一手になる。503は一時的な過負荷/メンテナンスを示すことが多い。

Catalyst Centerから全ネットワーク機器の在庫を取得し、機器ごとにインタフェース情報を追加取得するスクリプトを運用しているとします。ある朝、実行ログに次の3つの応答が順に記録されていました。まず在庫取得のGET /dna/intent/api/v1/network-deviceが401 Unauthorizedを返し、続いて再実行後の同じ呼び出しが200 OKで機器500台分のリストを返し、その後の機器ごとのインタフェース取得ループの途中から429 Too Many Requestsが連続した、という記録です。ここで多くの人が犯す誤りは、401を見て「アカウントの権限が足りない」と判断し、管理者にロール昇格を依頼してしまうことです。しかし401は認証の失敗（誰であるかが確認できない）であり、権限不足を示すのは403（認証は通ったが許可されていない）です。ログでは再実行しただけで200になっている——つまり資格情報もロールも正しく、単にトークンが有効期限切れだったと読むのが正しい診断です。恒久対策はロール変更ではなく、トークンの有効期限を管理し、401を受けたら自動で/auth/tokenから再取得して1回だけ再試行する処理をスクリプトに入れることです。次に429ですが、これを「サーバが壊れた」と読んで即座に何度も再試行するのは最悪手で、レート制限をさらに踏み抜いて回復を遅らせます。429はコントローラが「呼びすぎだ」と明示している状態なので、Retry-Afterヘッダがあればその秒数だけ待ち、無ければ指数バックオフ（1秒→2秒→4秒…）で間隔を空けます。より構造的な改善は、500台に対して1台ずつ問い合わせる設計自体を見直し、まとめて取得できるエンドポイントやページネーションを使って呼び出し回数を削減することです。もしここで返っていたのが500であれば診断は逆になり、リクエストは正しいのにコントローラ側で処理が失敗しているので、ペイロードやトークンをいじるのは的外れ——バックオフして再試行しつつ、コントローラのヘルスとログを確認します。また、機器を新規登録するPOSTが202やタスクIDを含む本文を返した場合、「まだ完了していない」ことを意味するため、タスク照会のエンドポイントをGETして完了を確認するまで成功と見なしてはいけません。逆に削除のDELETEが204 No Contentを返したとき、本文が空だからと失敗扱いして再実行するのは危険です——204は成功したが返す内容が無いことを意味し、実際には削除は完了しています。要するにENCORが問うのは、コードの語義そのものではなく、「そのコードが返ったとき、直すべきはペイロードか・資格情報か・権限か・URLか・呼び出し頻度か、それとも何も直さず待つべきか」という一手の選択です。

6.3.3この節のまとめ

• Catalyst CenterのIntent APIもSD-WAN Manager（vManage）も、認証を別リクエストで行いトークン/セッションをヘッダで提示する型は共通
• コードは責任の所在で三分する——2xx＝成功（204も成功）／4xx＝呼び出し側（400payload・401token・403権限・404URL・429頻度）／5xx＝サーバ側
• 問われるのは語義ではなく次の一手＝401はトークン再取得・403は権限見直し・429はRetry-Afterと指数バックオフ・5xxは内容を変えずバックオフ再試行