WordPress REST APIのエラー解決法

こんにちは、AIシステムズです。
この記事は、代表コバが現場で対応してきたWordPress開発の知見をもとに、AIを活用して構成・執筆し、弊社にて最終チェックを行ったものです。

WordPress REST APIを叩いたら「rest_no_route」「rest_forbidden」「401 Unauthorized」「CORS error」など、似たようなエラーが返ってきて何が原因かわかりにくい——フロントエンドからWordPressをヘッドレスCMSとして使う構成で頻発するトラブルです。REST APIのエラーは、原因がパーマリンク・認証・パーミッション・CORSの4種類に集約されるため、切り分け順を覚えれば短時間で解消できます。

• WordPress REST APIで起きる代表的なエラー
• パーマリンク設定の影響
• 認証方式（Cookie・Application Password・JWT）の使い分け
• カスタム投稿タイプをAPIで公開する方法
• CORS設定との関係

目次

1. REST APIで起きるエラーの分類
2. 原因を切り分ける順序
3. 認証方式ごとの設定
4. カスタム投稿タイプの公開設定
5. こういうサイトに向いている／向いていない
6. 再発防止チェックリスト

REST APIで起きるエラーの分類

弊社がヘッドレスWordPressの構築・保守で対応してきた中で、エラーは次の4つに分類できます。

• rest_no_route：エンドポイントが存在しない（パーマリンク・ルート未登録）
• rest_forbidden：エンドポイントはあるが権限不足
• 401 Unauthorized：認証情報が不足・不正
• CORS error：ブラウザ側で別オリジンへのアクセスがブロックされている

それぞれ原因が異なるため、まずブラウザの開発者ツールのNetworkタブで実際のステータスコードとレスポンスJSONを確認するのが第一歩です。

原因を切り分ける順序

1. パーマリンク設定を確認

WordPressのREST APIは、パーマリンク設定が「基本」（?p=123形式）だと動作しません。管理画面の「設定 → パーマリンク」で「投稿名」など別の形式に切り替え、保存します。これだけで rest_no_route が解消するケースがあります。

2. エンドポイントを直接ブラウザで開く

https://example.com/wp-json/wp/v2/posts

ブラウザで開いて投稿一覧のJSONが返れば、基本ルートは動いています。404が返るなら、サーバー側のリライト設定（nginxの設定や.htaccess）が原因の可能性があります。

3. 認証ヘッダーを確認

書き込み系（POST/PUT/DELETE）や非公開データの取得は認証が必要です。クライアントから送っているリクエストの Authorization ヘッダーが正しい形式で付いているかを確認します。

認証方式ごとの設定

Cookie認証（同一ドメインのフロントエンド向け）

WordPress管理画面と同じドメインのフロントエンドからAPIを叩く場合、ログイン済みのCookieが自動で送られるため、追加で X-WP-Nonce ヘッダーを送るだけで認証できます。

fetch('/wp-json/wp/v2/posts', {
    headers: { 'X-WP-Nonce': wpApiSettings.nonce },
    credentials: 'same-origin',
});

Application Password（推奨）

WordPress 5.6以降の標準機能で、ユーザーごとにアプリ用のパスワードを発行できます。外部システムからAPIを叩く場合の第一選択です。

curl -u username:xxxx-xxxx-xxxx-xxxx \
    https://example.com/wp-json/wp/v2/posts

JWT認証（外部公開API向け）

JWT Authentication for WP REST APIプラグインなどを導入し、トークンベースで認証します。SPAやモバイルアプリ向けに適しています。

カスタム投稿タイプの公開設定

カスタム投稿タイプをREST APIで取得できるようにするには、register_post_type で show_in_rest を有効にする必要があります。

register_post_type('tips', [
    'public' => true,
    'show_in_rest' => true,
    'rest_base' => 'tips',
    'supports' => ['title', 'editor', 'thumbnail'],
]);

既存のカスタム投稿タイプで show_in_rest が抜けていると、/wp-json/wp/v2/tips が rest_no_route になります。カスタムフィールド（ACFなど）をAPIに含めたい場合は register_rest_field で個別に登録します。

CORS設定との関係

別ドメインのフロントエンドからAPIを叩く構成では、サーバー側でCORSヘッダーを返す必要があります。WordPress側で rest_pre_serve_request フィルターを使って制御するか、nginx/Apache側で許可ヘッダーを返します。

add_filter('rest_pre_serve_request', function ($value) {
    header('Access-Control-Allow-Origin: https://frontend.example.com');
    header('Access-Control-Allow-Credentials: true');
    header('Access-Control-Allow-Headers: Authorization, Content-Type, X-WP-Nonce');
    return $value;
});

こういうサイトに向いている／向いていない

REST APIの整備は、フロントエンドをNext.js・Nuxt等で分離するヘッドレスWordPress構成や、外部システム（業務システム・モバイルアプリ）と連携するサイトに直接効きます。一方、表示も管理もWordPress内で完結する一般的なコーポレートサイトでは、REST APIに触る機会はほとんどありません。

再発防止チェックリスト

• パーマリンクが「基本」以外に設定されているか
• カスタム投稿タイプに show_in_rest が指定されているか
• 認証方式が用途に合っているか（社内連携はApplication Password、外部公開はJWT）
• クロスドメインの場合、CORSヘッダーが正しく返っているか
• 本番環境で WP_DEBUG を無効化してエラーがJSON経由で漏れていないか

まとめ

WordPress REST APIのエラーは、エラーコードごとに原因領域が決まっています。パーマリンク→ルート登録→認証→CORSの順で切り分けると、短時間で問題箇所を特定できます。

本記事は、代表コバがWordPress開発・ヘッドレス構成の現場で対応してきた知見をもとに、AIを活用して構成・執筆し、弊社にて最終確認を行っています。WordPressのAPI連携、ヘッドレス化、外部システム連携について、具体的な状況をふまえた相談を承っています。費用感だけ知りたい方も、お気軽にご相談ください。