WordPress REST API が 404 を返す場合

このエラーの意味と見分け方

• /wp-json/ を開くと、REST API インデックスの JSON ではなく HTTP 404 ページが表示される。
• JavaScript アプリケーション、モバイルアプリ、REST クライアント、エディター、または連携システムが、WordPress API リクエストに対して 404 Not Found を報告する。
• WordPress のフロントエンドは正常に読み込まれるが、REST リクエストは失敗する。
• /wp-json/ のきれいな URL パスが 404 を返す一方で、?rest_route=/ は機能する。
• API インデックスは読み込まれるが、プラグインまたはカスタムエンドポイントが 404 を返す。
• WordPress Site Health が REST API を利用できないと報告する。ただし、原因を特定するにはレスポンス本文とステータスコードも確認する必要がある。

可能性の高い順の主な原因

1. パーマリンクのリライトルールが古い、または存在しない。 移行、パーマリンク変更、サーバー変更、不完全なデプロイの後によく発生します。
2. Web サーバーまたはプロキシが /wp-json/ を WordPress に転送していない。 Apache の rewrite サポート、Nginx の try_files ルーティング、ドキュメントルートのマッピング、またはバーチャルホスト設定が正しくない可能性があります。
3. セキュリティ、ファイアウォール、CDN、キャッシュ、またはホスティングのルールが 404 を返している。 一部の制御機能は、ブロックしたリクエストに対して forbidden ではなく not found を返して存在を隠します。
4. プラグインまたはテーマが REST の動作を変更している。 ルートの削除、アクセス制限、REST レスポンスのフィルタリングなどが行われる場合があります。
5. 1つのカスタムまたはプラグインのエンドポイントだけが正しくない。 名前空間、ルート、バージョン、HTTP メソッド、リソース ID が間違っている、またはルートが登録されていない可能性があります。
6. リクエストが誤ったインストールパスまたはサイトを対象にしている。 ドメイン変更、サブディレクトリへのインストール、リダイレクト、古いアプリケーション設定、キャッシュされたレスポンスにより、クライアントが古い API のベースパスを使い続けることがあります。

修正方法

1. 404 の範囲と発生元を確認する

正確なリクエストパス、HTTP ステータス、レスポンス本文、レスポンスヘッダー、リクエストメソッド、タイムスタンプを記録します。レスポンスが WordPress、Web サーバー、リバースプロキシ、CDN、セキュリティレイヤーのどこから返されたように見えるかを確認します。診断記録にアクセストークン、Cookie、パスワード、非公開のレスポンスデータを含めないでください。

適切なクライアントから /wp-json/ で REST API インデックスをテストします。インデックスが JSON を返すのに1つのエンドポイントだけが 404 を返す場合は、手順 5 に進みます。インデックス自体が 404 を返す場合は、次に進みます。

2. WordPress のリライトルールを更新する

WordPress のダッシュボードで 設定 → パーマリンクを開き、選択されているパーマリンク構造を変更せずに 変更を保存をクリックします。これにより WordPress のリライト設定が更新されます。

もう一度 /wp-json/ をテストします。デプロイの自動化やホスティングのコントロールパネルがサーバー設定を管理している場合は、リライト設定が保持され、次回のデプロイで上書きされないことを確認します。

3. きれいな URL パスとフォールバックルートを比較する

WordPress のクエリパラメーターによるフォールバックを使って REST API をテストします。?rest_route=/ をサイトの通常のホームアドレスに追加してください。実際のスキーム、ホスト名、インストールパスを使用します。サブディレクトリへのインストールでは、そのパスをリクエストの一部として残す必要があります。

• フォールバックは機能するが /wp-json/ は失敗する場合： WordPress は REST リクエストを処理できているため、きれいな URL のリライト、バーチャルホスト設定、プロキシルーティング、ドキュメントルートのマッピング、移行時の変更を調査します。
• 両方とも失敗する場合： セキュリティ制御、サーバーのフロントコントローラーのルーティング、WordPress とプラグインの動作、設定されたサイトまたはインストールパスを確認します。
• 両方のインデックスリクエストは機能するが、1つのカスタムルートだけが失敗する場合： 手順 5 でそのエンドポイントを個別に診断します。

4. Web サーバー、プロキシ、セキュリティのルーティングを確認する

Apache の場合は、権限を持つ管理者に WordPress ディレクトリで rewrite サポートが有効になっていること、サイトのリライトルールが存在し、バーチャルホスト設定で許可されていることを確認してもらいます。Nginx またはリバースプロキシの場合は、リクエストが WordPress のフロントコントローラーに到達していること、/wp-json/ が存在しない静的ファイルとして扱われていないことを確認します。

関連する記録を次の順序で確認します。

1. 失敗したリクエストに関する Web サーバーのアクセスログとエラーログ。
2. CDN、ロードバランサー、リバースプロキシのルールとキャッシュエントリ。
3. WordPress のセキュリティ、ファイアウォール、ログイン保護、REST 制御プラグイン。
4. パス、メソッド、リクエストヘッダーをブロック対象として分類している可能性がある、ホスティングレベルの WAF ルール。

一度に1つの制御された変更だけを行い、元の設定を記録し、承認を得たうえで関連するキャッシュだけをパージします。承認済みのメンテナンス計画なしに、本番環境のファイアウォールやセキュリティプラグインを広範囲に無効化しないでください。セキュリティルールが原因の場合は、すべての保護を回避するのではなく、必要な REST パスとメソッドだけを限定的に許可します。

5. 1つの見つからないエンドポイントを診断する

エンドポイントの正確な名前空間、ルート、バージョン部分、HTTP メソッド、末尾のパス、リソース識別子を確認します。リクエストを、プラグインまたはアプリケーションが提供するルートのドキュメントや登録コードと比較します。

次の点を確認します。

• テスト対象の環境で、担当するプラグインまたはテーマが有効になっている。
• REST の初期化中にルート登録が実行されている。
• ルートに想定された permission callback があり、現在のリクエストに対して条件付きで除外されていない。
• クライアントが古いドメイン、サブディレクトリ、またはキャッシュされたアプリケーション設定ではなく、現在のサイトの API ベースパスを使用している。
• 要求されたリソースが実際に存在する。投稿、ユーザー、商品、その他のリソースが存在しない場合、REST API が正常でも、エンドポイントレベルの正当な 404 が返されることがあります。

利用できる場合は、API インデックスまたはルート検出レスポンスを確認します。想定されたルートが存在しない場合は、問題を一般的な REST 障害として扱うのではなく、登録、プラグインの状態、名前空間、環境固有の設定を調査します。

6. 制御された変更の後に再確認する

ブラウザー、承認済みの API クライアント、必要に応じてエラーを報告したアプリケーションから再テストします。各変更の前後で、ステータスコード、レスポンスヘッダー、レスポンス本文、レスポンスの発生元を比較します。一時的な診断変更を元に戻し、最終的なリライト、ファイアウォール、キャッシュ、プロキシ、またはプラグイン設定を記録します。

予防と修正確認

• 移行およびデプロイのチェックに、/wp-json/ と業務上重要な各カスタムルートの REST API スモークテストを追加する。
• WordPress のサイト URL、ホーム URL、ドキュメントルート、サブディレクトリ設定を環境間で一貫させる。
• リライト設定、プロキシルール、ファイアウォールポリシー、キャッシュの動作を、文書化されたデプロイ設定として管理し、文書化されていないサーバー変更に依存しない。
• セキュリティプラグインと WAF の変更が、認証済み・未認証の両方の REST リクエストに与える影響を確認する。
• 重要な API 呼び出しのレスポンスステータスと発生元を監視し、プロキシが生成した 404 と WordPress が生成した 404 を区別できるようにする。
• カスタム名前空間、ルート、対応メソッド、権限の動作、各エンドポイントを担当するプラグインまたはテーマを文書化する。