resource=calendar.latestWeek（軽量）で判定できますresource=market.report を1回取れば、クエリ・上位サイト・順位が揃います。個別の resource を複数回叩くより経済的ですrate limit exceeded（分単位）は Retry-After ヘッダー秒数を待って再試行、monthly quota exceeded（月間）は翌月まで待つか管理者に相談してくださいapi key plan does not permit scope '...'）になりますwarnings が付くことがあります（例: その市場・週に流入チャートデータが無い場合、クエリのみの部分成功）。エラーではありませんvalidUntil ≒ 分析日 + 28日）。期限後は再分析が必要ですエラーは {"detail": "..."} 形式で返ります。まず HTTP ステータスと detail の文言で切り分けてください。
| 症状 | 原因と対処 |
|---|---|
| 400 unknown resource / missing required params | resource 名の誤り、または必須パラメータ（marketId, fileId 等）の不足。レスポンスの available / detail に正しい一覧・不足項目が入っている |
| 401 invalid api key / invalid gateway key | キーの値が壊れているか、失効済み（ローテーションで旧キーを使い続けている等）。ダッシュボードの「API キー」画面で再発行し、プログラム側のキーを差し替える |
| 401 upstream login failed | kwtool のパスワード変更などで、キーに封入された認証情報が古い。ダッシュボードに再ログインしてキーを再発行 |
| 401 wrong credential (remaining: N) | ログインの ID/PW が誤り。残り試行回数に注意（5回失敗で10分ロック） |
| 403 api key plan does not permit resource / scope | キーのプランにその resource（データ範囲）の権限が無い。管理者にプラン変更を相談 |
| 403 API の利用には管理者による利用許可が必要です | アカウントに API 利用許可が未登録（トライアル状態）。サポートチームに発行を依頼 |
| 403（プロジェクト系） | そのプロジェクト/データへの権限がアカウントに無い |
| 404 market not found | 市場名の完全一致に該当なし。表記（スペース・カタカナ・全角半角）を確認。ダッシュボードの API 体験で市場検索して正確な名前を確かめるのが早道 |
| 422 | パラメータ不足・形式誤り。レスポンスの detail（配列）に不正フィールドの位置（loc）と理由（msg）が入っている |
| 429 rate limit exceeded | 分単位のレート制限超過。Retry-After 秒待って再試行。ループ取得は直列・低頻度に |
| 429 monthly quota exceeded | キーの月間上限に到達。翌月を待つか、管理者に上限変更を相談 |
| 502 upstream kw-cms error | kwtool 側のエラー。多くは「その市場・週にデータが無い」。weekEnd を変えるか、時間を置いて再試行 |
| 日本語パラメータで失敗する | URL エンコード漏れの可能性。curl は -G --data-urlencode を使う（共通ルール参照） |
| 分析がいつまでも researched にならない | status 照会の marketId（scId）が request 時と違う可能性。request に使った scId で照会する（標準フローの注意参照） |
解決しない場合は、実行した URL（キーは伏せる）・HTTP ステータス・レスポンスの detail を添えて管理者にお問い合わせください。
問い合わせ: kw-platform-api 管理者まで。 ← ダッシュボードへ戻る