YouTube Data API v3 エラー一覧｜403・400・404 の原因と対処

YouTube Data APIのエラーは、HTTP状態だけでなく呼び出したメソッド・本文のreason・認証方式・実行元を合わせて確認します。403は「キーがない」とは限らず、認可や割当の不足でも発生します。以下は診断手順であり、キー発行・制限解除・OAuth更新・再送を自動で行うものではありません。

最初に確認する情報

1. どのメソッドか。videos.listとsearch.list、更新/削除では必要な認可や割当が異なります。操作を追加して再現試験しません。
2. 通信失敗かHTTP応答か。DNS/TLS/timeoutと、400/401/403等の応答を分けます。HTTP応答がない失敗を、保存されなかった証明としません。
3. 応答本文がJSONか。error.codeとerrors[].reason等を確認し、HTMLや不正JSONなら別経路のエラーも疑います。messageの文言だけに依存しません。
4. どのプロジェクト・資格情報・ユーザーで送信したか。実値のキー/token/Authorization/Cookie/URLクエリや応答全文を、公開画面やログへ出しません。

認証・認可・キー制限を区別する

公開データを取得するAPIキーと、ユーザーの非公開データや操作を認可するOAuthは別です。OAuthクライアントIDやclient secretを、そのままAPIキーやaccess tokenとして送ることもできません。アップロード等のOAuth必須メソッドは、キーの付け替えだけでは利用できません。

401ならaccess tokenの期限・失効・形式・対象を確認しますが、必ずrefresh tokenがあるとは限りません。refreshの失敗を無限に繰り返さず、必要な場合はユーザーの再認可を正式フローで行います。403のinsufficientPermissions等ではscope・ユーザー/チャンネル・対象の権限を確認し、scopeを無条件に最大化しません。

HTTPリファラー制限はブラウザ向け、送信元IP制限はサーバー向けの選択肢です。実際にAPIへ通信する層に合わせて、アプリケーション制限と利用APIの制限を照合します。バックエンドのcurlへブラウザ用キーを渡して失敗した場合に、Refererを偽装したり制限を外したりしません。開発用の広いワイルドカードを本番へ追加することも避けます。

reason別の確認先

reasonの形はAPIやエラー経路で異なり、上表は網羅表ではありません。videos.listのID指定で対象が返らない場合も、常に404とは限らずitemsが空になることがあります。200でも必要な結果があるか確認します。YouTubeサイトで再生できることは、別ユーザー/別操作のAPIアクセス成功の証明ではありません。

現在の割当と過去の数字を混同しない

2026年10月26日に確認した公式割当表では、search.listとvideos.insertはそれぞれ既定100呼出し/日の独立枠で、1呼出しのコストは各枠の1です。その他は既定合計10,000 units/日の枠として案内されています。実プロジェクトの値はCloud Consoleで確認し、既定値を契約/追加承認後の残量とみなしません。日次枠のリセット基準はPacific Timeの午前0時です。

古いsearch.list=100 units、videos.insert=1,600 unitsという記録から、一律10,000を割って現在の可能回数を出しません。ページを追加取得すれば追加の呼出しとなり、不正な要求も割当を消費し得ます。part/fieldsを絞ることは転送量の削減には有用ですが、その操作の割当単価が下がる証明ではありません。

同じ検索の不要な呼出しやページ取得を抑え、既知IDを取得する用途なら適切なlistメソッドを検討します。ただし保存/キャッシュは開発者ポリシーの保持・更新・削除条件を確認して設計し、無期限保存を勧めません。この編集でCWikiの新規キャッシュを導入していません。増枠は公式の監査/申請手順に従い、承認日数や必ず承認されることを約束しません。

本文を外へ出さないオフライン分類例

次は手元で取得済みのHTTP状態と本文を受け取るPHP教材です。通信・資格情報読込・ログ・再送は行いません。本文は65,536byte、JSON深さ16、errorsは最大20件に限定し、既知のHTTP/reasonの組合せだけを分類します。生のmessageや未知のreasonは返しません。複数カテゴリならmultiple、形式不正/未知/HTTP不一致はunclassifiedです。

<?php
declare(strict_types=1);

/** Offline teaching helper: no network, credentials, logs, refresh or retries. */
function summarizeYouTubeError(int $httpStatus, string $body): array
{
    $unknown = ['category' => 'unclassified', 'reason_codes' => [], 'automatic_retry' => false];
    if ($httpStatus < 400 || $httpStatus > 599 || strlen($body) > 65536) {
        return $unknown;
    }
    try {
        $data = json_decode($body, false, 16, JSON_THROW_ON_ERROR);
    } catch (JsonException) {
        return $unknown;
    }
    if (!$data instanceof stdClass || !isset($data->error) || !$data->error instanceof stdClass
        || !isset($data->error->code) || $data->error->code !== $httpStatus
        || !isset($data->error->errors) || !is_array($data->error->errors)
        || count($data->error->errors) < 1 || count($data->error->errors) > 20) {
        return $unknown;
    }
    $known = [
        400 => ['incompatibleParameters' => 'parameters', 'invalidFilters' => 'parameters',
            'invalidPageToken' => 'parameters', 'missingRequiredParameter' => 'parameters',
            'unexpectedParameter' => 'parameters'],
        401 => ['authError' => 'credentials'],
        403 => ['quotaExceeded' => 'quota', 'dailyLimitExceeded' => 'quota',
            'forbidden' => 'authorization', 'insufficientPermissions' => 'authorization',
            'accessNotConfigured' => 'api_configuration', 'rateLimitExceeded' => 'rate_limit',
            'userRateLimitExceeded' => 'rate_limit'],
        404 => ['videoNotFound' => 'resource', 'channelNotFound' => 'resource',
            'playlistNotFound' => 'resource'],
    ];
    $categories = [];
    $codes = [];
    foreach ($data->error->errors as $entry) {
        if (!$entry instanceof stdClass || !isset($entry->reason) || !is_string($entry->reason)
            || !isset($known[$httpStatus][$entry->reason])) {
            return $unknown;
        }
        $codes[$entry->reason] = true;
        $categories[$known[$httpStatus][$entry->reason]] = true;
    }
    $reasons = array_keys($codes);
    sort($reasons, SORT_STRING);
    return [
        'category' => count($categories) === 1 ? array_key_first($categories) : 'multiple',
        'reason_codes' => $reasons,
        'automatic_retry' => false,
    ];
}

これは認証/アクセス制御や自動復旧ではありません。Content-Type判定、受信時の容量/時間上限、JSONの重複キー検査、全てのGoogleエラー形式、資格情報の安全な管理は呼出し側で別に扱います。HTTP200でerror本文だった場合もこの関数の対象外です。取得済み本文が秘密を含むこともあるため、分類前の本文をログへ出さないでください。

元の操作例について

以下の元コード例は保守資料として保持します。上の診断方針と直前の注意を先に読み、資格情報を埋めてそのまま実行しないでください。

YouTube Data API (v3) のエラー

このページは、YouTube Data API (v3) で発生しやすいエラーの入口です。まずは API キー不足なのか、リファラー制限の問題なのか、クォータ超過なのかを切り分けて確認すると、原因にたどり着きやすくなります。

代表的なエラー

Requests from referer ... are blocked. の見方

このメッセージではHTTPリファラー制限と実行元の不一致を調べます。ブラウザかサーバーかを区別し、実際のリクエスト経路を確認します。Referer偽装や制限解除で直そうとしません。

確認するべきこと

1. Google Cloud Console → APIs & Services → 認証情報
2. 該当 API キーをクリック
3. アプリケーションの制限: 実行元に適した方式か。ブラウザのHTTPリファラーとサーバーのIP制限を分ける
4. ウェブサイトの制限: アクセス元のドメインが含まれているか
   • 例: https://example.com/*
   • サブドメイン含めるなら https://*.example.com/*
   • 開発用設定を本番へ追加しない。必要なテスト用のhost/portだけを公式の制限書式で確認する
5. API の制限: 「YouTube Data API v3」が選択されているか

クォータ消費の目安

検索の不要な繰返しを減らすため、用途と公式ポリシーに合わせて以下を検討します。単価と速度を同じ意味の「重い」で断定しません。

• 同じ要求を抑える。保存/キャッシュはポリシーの保持・更新・削除条件を先に確認する
• 動画 ID を取って後は videos.list で詳細取得
• 必要な件数とページ取得を設計する。常にmaxResults最大が最適とは限らない
• 必要なら公式の監査/増枠申請へ。承認の可否や日数は約束しない

API キーの取得手順（おさらい）

旧例の注意：旧手順は全環境へHTTPリファラー制限を指定していますが、実行元により制限方式が異なります。既存キーをむやみに発行/変更せず、上の診断を参照してください。

1. Google Cloud Console (console.cloud.google.com) にログイン
2. プロジェクトを作成 / 選択
3. 左メニュー → APIs & Services → ライブラリ
4. "YouTube Data API v3" を検索 → 「有効にする」
5. 左メニュー → 認証情報 → 「認証情報を作成」→ API キー
6. キーが発行されるので「キーを制限」で:
   - アプリケーションの制限: HTTP リファラー
   - ウェブサイト: 自サイトドメインを追加
   - API の制限: YouTube Data API v3
7. キーをコピーして安全な場所に保存（公開リポジトリに絶対 push しない）

動作確認用 curl

旧例の注意：旧curlはキーをURLへ入れています。実キーを置換してシェル履歴/プロセス引数/アクセスログへ残さず、公式クライアント等の資格情報管理を利用します。HTTPSでもURL記録への露出は防げません。200だけで必要なitemsの取得も保証しません。

# 動画詳細取得（API キーは必ず HTTPS 経由で）
curl "https://www.googleapis.com/youtube/v3/videos?part=snippet,statistics&id=dQw4w9WgXcQ&key=YOUR_API_KEY"

# 期待される結果: 200 OK + JSON
# 403: API キーまたはリファラー制限の問題
# 400: パラメータ不正

関連

• 秘密値はフロントエンド/リポジトリへ埋め込まない。公開クライアントから見えるキーの制限と、サーバーでの資格情報管理を区別する
• 商用利用は API 利用規約と YouTube ブランドガイドラインに従う
• 埋め込みプレーヤーは API キー不要で <iframe> で済むケースが多い
• 動画分析・統計用途では YouTube Analytics API（別 API）が必要なケースあり

公式資料と検証範囲

2026年10月26日確認。掲載PHPの分類は合成応答だけで検査し、GoogleへのAPI通信・実キー・OAuthログイン/refresh・Cloud設定変更・課金/アップロード/削除・実サービスの全エラー形式は検証していません。本文の不明なmessageを推測で原因へ変換しません。

YouTube Data APIの親ページから子ページを選べます。このエラー一覧には確認時点で直接の子ページはありません。以前の「子ページからエラーを選択」という案内を、存在しない子ページへの誘導として再掲しません。

公式資料：YouTube APIのエラー、最新の割当表、search.list、videos.insert、OAuthの用途、APIキーの制限、キーの安全な管理、OAuth Web Serverフロー、監査と増枠申請、開発者ポリシー。