最終更新 2026年11月1日

エラー

2xx 以外のレスポンスはすべて、同じ 4 つのフィールドを持つ JSON エンベロープです。code で分岐し、message は人に向けて表示し、requestId はログに残し、retryable が true のときだけリトライしてください。

エンベロープ

429 Too Many Requests

{  "code": "rate_limit_exceeded",  "message": "API key rate limit exceeded.",  "requestId": "3f2b6c1e-8a4d-4f0e-9b7a-2d5c1e6f8a90",  "retryable": true}

フィールド	型	意味
`code`	string	`snake_case` の安定した機械可読の識別子です。分岐にはこちらを使い、`message` では分岐しないでください。
`message`	string	英語による人が読める説明です。運用担当者に表示しても問題ありませんが、文言は変わる可能性があります。
`requestId`	string	サーバーが生成するリクエストの UUID です。サポートへの問い合わせ時に添えてください。ログからリクエストを特定する唯一の手がかりです。
`retryable`	boolean	同じリクエストが変更なしで後に成功しうる場合（レート制限、一時的な障害）は `true` です。それ以外は、リクエストの内容を変える必要があります。

ステータスコードも重要です

HTTP ステータスは大まかな分類（4xx はクライアント側、5xx はこちら側）で、code が詳しい理由です。ステータスだけを見るクライアントは、スコープ不足とモジュールを含まないプラン（どちらも 403）を区別できません。

エラーの扱い方

以下は RoomScope のダッシュボード自身が使っているパターンです。エンベロープを解析し、ボディが JSON でない場合は http_error にフォールバックし、サーバーがリトライ可能と示したエラーだけを指数バックオフでリトライします。

class ApiError extends Error {  constructor(status, { code, message, requestId, retryable }) {    super(message);    Object.assign(this, { status, code, requestId, retryable: Boolean(retryable) });  }} async function call(path, init) {  const res = await fetch(`https://api.toktokdata.live${path}`, init);  if (res.ok) return res.status === 204 ? undefined : res.json();  let envelope = {};  try { envelope = await res.json(); } catch {}  throw new ApiError(res.status, { code: "http_error", message: `Request failed (${res.status})`, ...envelope });} // Retry only when the server says so.async function withRetry(fn, attempts = 3) {  for (let i = 0; ; i++) {    try { return await fn(); }    catch (e) {      if (!(e instanceof ApiError) || !e.retryable || i === attempts - 1) throw e;      await new Promise((r) => setTimeout(r, 500 * 2 ** i));    }  }}

ステータス別のコード

コードは安定していますが、新しいコードが追加されることがあります。未知のコードはステータスに基づいて扱ってください。リファレンスの各エンドポイントには、返しうるコードが記載されています。

ステータス	コード	発生条件	リトライ可否
400	`validation_error`	ボディまたはパラメーターの形式が不正です。メッセージに該当するフィールド名が含まれます。	不可
400	`invalid_rankings_input`	ランキング：board がない、128 文字を超える値がある、または limit、leagueTier、period、liveOnly の値が不正です。	不可
400	`invalid_cursor · invalid_region · invalid_trend_type`	エンドポイントが受け付けないカーソル、地域（insights では 2 文字）、またはトレンドの種類です。	不可
400	`invalid_live_history_input · invalid_alert_input · invalid_dataset · invalid_format`	エンドポイント固有の入力エラーです。修正すべき点はメッセージに記載されます。	不可
401	`unauthorized`	キーがない、形式が不正、不明、失効済み、期限切れ、またはワークスペースが無効です。WWW-Authenticate: Bearer ヘッダーとともに返されます。	不可
402	`credit_cap_exceeded`	このリクエストにより、期間内の消費がクレジット上限を超えます。	不可
403	`insufficient_scope`	キーに必要なスコープがない、またはダッシュボード専用のルートです。	不可
403	`module_not_entitled`	ワークスペースのプランに LIVE モジュールまたは検索モジュールが含まれていません。	不可
403	`export_format_not_entitled`	プランにそのエクスポート形式が含まれていません。	不可
404	`not_found`	メソッドとパスに一致するルートがありません。	不可
404	`creator_not_found · video_not_found · live_session_not_found · alert_not_found · export_not_found`	リソースが存在しないか、別のワークスペースに属しています。	不可
409	`export_not_ready · api_key_limit_reached`	エクスポートがまだ作成中か、プランのキー数の上限に達しています。	不可
429	`rate_limit_exceeded`	キーの 1 秒あたりのリクエスト数を超えました。Retry-After に従ってください。	可
429	`daily_quota_exceeded`	キーの 1 日あたりの上限を使い切りました。Retry-After は UTC の午前 0 時までの秒数です。	可
503	`rate_limit_unavailable · metering_unavailable · webhook_unavailable`	依存するサービスが停止しています。バックオフを入れてリトライしてください。	可
500	`internal_error`	こちら側で問題が発生しました。バックオフを入れてリトライし、報告の際は requestId を添えてください。	可

エラーではないケース

ランキングで不明な region や対象外の地域を指定してもエラーにはなりません。200 とともに publishable: false、空の entries 一覧、そして理由を示す provenance が返ります。
収集中のフォロー中、フォロワー、コメントは、202 とともに status: "collecting"、jobId、Retry-After ヘッダーを返します。指定された秒数が経過してから再度呼び出してください。

レート制限については専用のページがあります：レート制限。

このページは役に立ちましたか？