14. WordPress REST API投稿失敗時の原因特定とリカバリー手順
API連携における「想定外の失敗」への備え
外部システムからWordPressへコンテンツを自動投稿する際、最も陥りやすい罠は、APIが返すエラーメッセージを「単なるエラー」として処理してしまう点です。実際には、認証トークンの期限切れ、必須フィールドの欠落、またはデータ型の不一致など、複数の原因が絡み合っているケースがほとんどです。
API通信の検証：認証・権限・スキーマの三点チェック
API通信の成功は、単にHTTPステータスコード200を受け取ること以上の意味を持ちます。それは、「認証された主体が、指定された権限で、期待されるデータ構造を送信できた」という三つの条件が満たされたことを意味します。
投稿失敗時の系統的チェックフロー（3段階）
以下のフローで、問題の発生源を特定します。
| ステップ | 確認すべきレイヤー | 具体的な確認方法とアクション |
|---|---|---|
| 1. 認証と権限の確認 | APIキーやOAuthトークンが有効か、投稿に必要な権限（write権限など）を持っているか | トークンを再取得し、GET（読み取り）とPOST（書き込み）の両方でテスト実行する。権限不足の場合は、APIユーザーのロールを見直す必要がある |
| 2. データ構造（スキーマ）の検証 | 送信するデータが、WordPressが期待するフィールド構造と一致しているか | 必須フィールド（例：post_title, content）が全て含まれているか、また、カスタムフィールド（meta）のキー名やデータ型が正しいか、公式ドキュメントと照合する |
| 3. エラーレスポンスの深掘り | APIが返すエラーメッセージ（JSONボディ）を完全に読み込む | ステータスコードが4xxや5xxであっても、レスポンスボディ内のmessageやerrors配列に具体的な理由が記述されているため、これを最優先で参照する |
運用上の注意点
自動投稿処理では、同じ内容を再送してしまう（冪等性違反）リスクがあります。これを防ぐため、投稿時に一意の識別子（例：外部システムID）をカスタムフィールドとして付与し、そのIDをチェックするロジックを組み込むことが、運用上の必須要件となります。
まとめ：API通信は「契約」として扱う
API通信は、システム間の「契約」と見なすべきです。契約書（ドキュメント）に書かれているスキーマ、認証方法、ステータスコードの挙動を、コード実行前に全て確認することが、安定した自動化の鍵となります。
