contentAnalysis.status）resource=calendar.latestWeek（軽量）で判定できますresource=market.report を1回取れば、クエリ・上位サイト・順位が揃います。個別の resource を複数回叩くより経済的ですrate limit exceeded になります。Retry-After ヘッダーの秒数を待って再試行してくださいmonthly quota exceeded になります（Retry-After は付きません）。翌月まで待つか、サポートチームに相談してくださいlimit など）に固定の最大値はありません。ただし管理者が上限を設定している場合、上限を超えた値はエラーにならずに上限まで切り詰められますcontentAnalysis.request）と複ページ分析の依頼（contentAnalysis.linkRequest）には、ご契約区分ごとに別枠の1日あたりの上限があります（0 回/日は利用できないことを表します）
Retry-After: 3600 が付きますが、再び依頼できるのは日付が変わってからです。AI アプリ経由では「日付が変わると再依頼できます」と表示されます）result が over_limit または not_enabled のものだけです。それ以外の accepted: false は回数を消費することがありますdaily analysis request limit reached になり、日付が変わると再依頼できます（→ 5.4）warnings が付くことがあります（例: その市場・週に流入チャートデータが無い場合、クエリのみの部分成功）。エラーではありませんmarket.searchPartial で確かめられますvalidUntil ≒ 分析日 + 28日）。期限後は再分析が必要ですご契約区分が「KWTOOL 契約連動」「体験版」のアカウントでは、取得できる市場の範囲が kwtool のご契約の建て付けに合わせて制限されます。
対象: KWTOOL 契約連動 (connected) / 体験版 (trial) の API キーと、ダッシュボードのログインセッション。この表はサーバーの定義から自動生成しています。
| resource | 内容 | 判定に使う値 |
|---|---|---|
| market.report | マーケットレポート一括取得 (全クエリ + 上位サイト + クエリ別順位) | 市場名 (name) |
| market.queries | 市場の全クエリと検索ボリューム (軽量版) | 市場名 (name) |
| market.rankChart | ドメインの週次の流入・順位推移 | 市場名 (name) |
| market.urlChart | ドメインの下層ページ一覧 (調査済みドメインのみ) | 市場名 (name) |
| market.urlRankChart | URL 単位のクエリ別順位推移 | 市場名 (name) |
| market.researchedDomains | 下層ページ調査済みのドメイン一覧 | 市場名 (name) |
| market.urlResearchRequest | ドメインの下層ページ調査を依頼 (次回調査で反映) | 市場名 (name) |
| market.refreshRequest | 最新週でない市場のデータ更新を依頼 | 市場名 (name) |
| market.segments | カテゴリ別のクエリ内訳 (セグメント) | 市場 ID (marketId) |
| market.segmentPlans | セグメント計画の一覧 (カスタム分類を含む) | 市場 ID (marketId) |
| market.segmentPlanDetail | セグメント計画1件 (形態素グループ付き) | 市場 ID (marketId) |
| market.microSegments | ミクロセグメント | 市場 ID (marketId) |
| market.segmentPlanSave | セグメント計画の作成・更新 | 市場 ID (marketId) |
| market.portalScores | 市場内ドメインのポータル度 (0-1) | 市場 ID (marketId) |
| market.targetPlan | ターゲット計画 (クエリ別の受注確度) の取得 | 市場 ID (marketId) |
| market.targetPlans | ターゲット計画の一覧 | 市場 ID (marketId) |
| market.targetPlanSave | ターゲット計画の保存 | 市場 ID (marketId) |
| market.targetPlanDetail | 保存済みターゲット計画1件の全内容 | 市場 ID (marketId) |
| market.targetPlanNamedSave | 名前付きターゲット計画の保存 (新規・更新) | 市場 ID (marketId) |
| market.targetPlanDelete | 保存済みターゲット計画の削除 | 市場 ID (marketId) |
| projects.marketBookmark | プロジェクトに市場をブックマーク | 市場 ID (marketId) |
| projects.marketUnbookmark | プロジェクトの市場ブックマークを解除 | 市場 ID (marketId) |
| contentAnalysis.request | コンテンツ分析 (単ページ) の開始 | 市場 ID (marketId) |
reason: outside_my_markets）になります。kwtool で注目市場に登録してから再試行してください。登録が反映されるまで最大 300 秒かかりますmyMarkets.groupMarkets）で正確な名前を確認してくださいreason: data_range_unverifiable）になります。時間を置いて再試行してくださいエラーは {"detail": "..."} 形式で返ります（reason などの項目が付くこともあります）。まず HTTP ステータスと detail の文言で切り分けてください。403 の場合は、ダッシュボードの API キー 画面の あなたが利用できる機能 で、その機能が使えるか（利用制限中 になっていないか）を確認すると早く解決できます。リクエストごとの結果は 使用量・ログ で確認できます。症状欄の [ダッシュボード] は、ダッシュボードの操作で出るエラーです（通常の API キー kwk_ や AI アプリ経由では出ません）。
AI アプリ経由では、ツールの結果として「エラー: 認証/権限エラー (401): api key revoked」「エラー: レート/回数制限 (429): monthly quota exceeded」のように表示されます。括弧内のステータスと続く文言でこの表を引いてください。AI アプリの接続そのものの問題は → 6.7。
| 症状 | 原因と対処 |
|---|---|
| 400 unknown resource / missing required params | resource 名の誤り、または必須パラメータ（marketId, fileId 等）の不足。レスポンスの available / detail に正しい一覧・不足項目が入っている |
400 conflicting credentials（reason: credential_conflict） | ヘッダーと ?key=（またはヘッダー同士）で異なるキーを同時に送っている。キーは1本だけ送る |
| 401 missing api key | キーが送られていない。ヘッダー名（X-API-Key）や ?key= の書き方を確認 |
| 401 invalid api key | キーの値が誤っている（途中で切れている・余計な空白がある等）。控えたキーをそのまま貼り直す |
| 401 api key revoked | 失効済みのキー。有効なキーに差し替える（無ければ API キー 画面で新しいキーを発行） |
| 401 api key expired | キーの有効期限切れ。新しいキーを発行して差し替える。利用許可自体が期限切れで発行できない場合はサポートチームに相談 |
| 401 api key is not activated | 管理者から受け取った招待キーが未有効化。ログイン画面で初回有効化を行う（→ 2.3） |
| [ダッシュボード] 401 invalid gateway key / gateway session revoked; please log in again （「取得失敗 (HTTP 401)」と出る、またはログイン画面に戻される） | ダッシュボードのセッションが切れた（24 時間で切れます → 2.1）かログアウト済み。もう一度ログインする（キーの再発行は不要）。セッション用のキーをプログラムで使っていた場合は、API キー（kwk_）に切り替える |
| 401 upstream login failed | kwtool のパスワード変更などで、キーに封入された認証情報が古い。ダッシュボードに新しいパスワードで再ログイン → 新しいキーを発行 → 差し替え → 古いキーを失効 |
| [ダッシュボード] 401 kwtool login failed: …（remaining attempts: N） | ログイン（または招待キーの有効化）の ID/PW が誤り。残り試行回数に注意（連続 5 回失敗すると kwtool 本体の仕様でロック） |
| [ダッシュボード] 403 API の利用には管理者による利用許可が必要です | アカウントに API の利用許可が未登録（または期限切れ）。サポートチームに登録を依頼 |
| 403 api key plan does not permit resource '…' | キーのスコープ（使える機能）にその resource が含まれていない（requiredScope に必要なスコープが入っている）。あなたが利用できる機能 で確認し、必要ならサポートチームに相談。resource '…' の代わりに scope '…' と表示される場合も同じ意味 |
| 403 role '…' does not permit resource '…' | キーには含まれているが、ご契約区分の上限でその resource が使えない（画面では 利用制限中）。キーを再発行しても変わらないので、ご利用希望はサポートチームに相談。scope '…' と表示される場合も同じ意味 |
| [ダッシュボード] 403 account permissions do not permit resource '…' | アカウントの利用許可にその機能が含まれていない。あなたが利用できる機能 で確認し、必要ならサポートチームに相談。scope '…' と表示される場合も同じ意味 |
| 403 external api keys must use the single endpoint /v1/query | API キーで /v1/query 以外の URL（/v1/markets/... 等）を直接呼んだ。/v1/query?resource=… の形に書き換える（→ 共通ルール） |
403 market '…' is not in your registered my-markets（reason: outside_my_markets） | 注目市場に登録していない市場の詳細を取得しようとした（KWTOOL 契約連動・体験版）。kwtool で注目市場に登録し、最大 300 秒待ってから再試行。市場名の表記ゆれでも起きる（→ データ範囲） |
| 403 ご契約では…をご利用いただけません | ご契約区分ではコンテンツ分析（または複ページ分析）の依頼を利用できない。翌日になっても変わらないので、ご利用希望はサポートチームに相談（→ 投入上限） |
| 404 market not found | 市場名の完全一致に該当なし。表記（スペース・カタカナ・全角半角）を確認。部分一致検索 /v1/query?resource=market.searchPartial&query=… で正確な名前を確かめるのが早道（→ market.searchPartial） |
| 422 | パラメータ不足・形式誤り。detail の形は3通り: ①配列（loc に不正な項目の位置、msg に理由）、②オブジェクト（計画の保存などで reason や allowed に理由・許可値）、③文字列（不明な sort 指定など） |
| 429 rate limit exceeded | 分単位のレート制限超過。Retry-After 秒待って再試行。ループ取得は直列・低頻度に |
| 429 monthly quota exceeded | アカウント全体（全キー＋ダッシュボード操作の合計）が月間上限に到達。キーを分けても解消しない。翌月を待つか、サポートチームに上限変更を相談 |
| [ダッシュボード] 429 リクエストが集中しています。少し時間をおいて再試行してください | 操作が短時間に集中した。少し待ってから操作する |
| 429 status polled too frequently for this analysis; retry after Ns | 同じ分析の状況照会（contentAnalysis.status）を 10 秒未満の間隔で繰り返した。Retry-After 秒待ってから照会する（照会自体は非課金） |
| [ダッシュボード] 429 too many login attempts; retry after N seconds | 短時間にログイン（または招待キーの有効化）を繰り返した。表示された秒数を待ってから再試行 |
| 429 upstream login throttled （AI アプリでは「kwtool ログインの一時制限」と表示） | kwtool 側でログインが一時的に制限されている（短時間にログインが重なった時の kwtool の保護。reason: upstream_login_throttled）。キーの再発行は不要。Retry-After 秒（既定 900 秒＝15 分）待ってから再試行する。待たずに再試行・再ログイン・キーの再発行を繰り返すと制限が延びる（同じ kwtool アカウントを使う他の接続も待つ必要がある） |
| 429 1日あたりの…の上限に達しました | コンテンツ分析（または複ページ分析）の依頼が、ご契約区分の1日あたりの上限に到達。日付が変わってから再依頼する（→ 投入上限） |
| 429 daily analysis request limit reached | （データ提供契約）管理者が設定した、コンテンツ分析の1日あたりの依頼数の上限に到達。日付が変わってから再依頼するか、サポートチームに相談 |
| 502 upstream kw-cms error (HTTP 403)（プロジェクト系） | そのプロジェクト・データへの権限がアカウントに無い（プロジェクトの詳細や市場一覧など）。kwtool 側でプロジェクトの権限を確認 |
| 502 upstream kw-cms error | kwtool 側のエラー。多くは「その市場・週にデータが無い」。weekEnd を変えるか、時間を置いて再試行 |
| 502 upstream business error for resource … | kwtool 側がその依頼を業務エラーとして返した。パラメータを見直す。解決しない場合は下記の情報を添えて問い合わせ（このエラーは課金されない） |
503 現在データ転送を一時停止しています。管理者にお問い合わせください（killSwitch: true） | 管理者（＝サポートチーム）がデータ転送を緊急停止している（API・AI アプリ連携・ダッシュボードのデータ取得がすべて止まる）。再開まで待つか、サポートチームに問い合わせ |
503 契約データ範囲 (注目市場) を確認できないため…（reason: data_range_unverifiable） | 注目市場の一覧を一時的に確認できないため、安全側で拒否した。時間を置いて再試行 |
503 認可の確認に失敗したため…（reason: guard_unavailable） | 権限を確認する仕組みの一時的な障害で、安全側で拒否した。時間を置いて再試行 |
| 日本語パラメータで失敗する | URL エンコード漏れの可能性。curl は -G --data-urlencode を使う（共通ルール参照） |
| 分析がいつまでも researched にならない | status 照会の marketId（scId）が request 時と違う可能性。request に使った scId で照会する（標準フローの注意参照） |
解決しない場合は、実行した URL（キーは伏せる）・HTTP ステータス・レスポンスの detail を添えてサポートチームにお問い合わせください。
問い合わせ: サポートチームまで。 ← ダッシュボードへ戻る