エラーコード

TWP公開APIが返すエラーコードの一覧です。

エラーレスポンス形式


{
  "error": {
    "code": "ERROR_CODE",
    "message": "エラーの説明"
  }
}

バリデーションエラー（問い合わせAPI）の場合は、詳細情報が含まれます。


{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "入力内容に誤りがあります。",
    "details": [
      {
        "field": "inquirer_email",
        "message": "メールアドレスの形式が正しくありません"
      }
    ]
  }
}

共通エラーコード

認証・認可

APIキーの検証はAPIゲートウェイで行われるため、認証の段階で拒否されたときは error オブジェクトを持たない次の形で返ります。キーが無い・形式が違う・存在しない・無効化済み・有効期限切れ・テナントが利用停止中のいずれも同じ応答で、理由は区別されません。


{ "message": "Forbidden" }

状況	HTTPステータス	レスポンス
APIキーが無い・無効・無効化済み・期限切れ	403	`{"message": "Forbidden"}`
そのAPIに必要な権限がキーに無い	403	`error.code`: `FORBIDDEN`（`Insufficient permissions`）
MCP接続（OAuth）の資格情報で呼び出した	403	`error.code`: `FORBIDDEN`
クレジット不足・API利用の無効化	403	下記の形式

クレジット不足などでAPIの利用が止まっているときは、次の形式で返ります。error_code は credit_exhausted（クレジット残高不足）または manually_disabled（管理者による無効化）です。


{
  "message": "Forbidden",
  "error_code": "credit_exhausted",
  "error_description": "テナントのクレジット残高が不足しているため、APIの利用が一時停止されています。"
}

リクエスト

コード	HTTPステータス	説明
`MISSING_BODY`	400	リクエストボディが空
`INVALID_JSON`	400	JSONのパースエラー
`VALIDATION_ERROR`	422	バリデーションエラー（問い合わせAPI）
`NOT_FOUND`	404	リソースが見つからない
`METHOD_NOT_ALLOWED`	405	許可されていないHTTPメソッド

サーバー

コード	HTTPステータス	説明
`INTERNAL_ERROR`	500	サーバー内部エラー

短時間にリクエストが集中した場合は、429 と {"message": "Too Many Requests"} が返ることがあります（error オブジェクトは付きません）。間隔を空けてリトライしてください。

コンテンツAPI固有のエラー

コード	HTTPステータス	説明
`CATEGORY_NOT_FOUND`	404	指定されたカテゴリが存在しない
`MISSING_CATEGORY`	400	カテゴリの指定が必要
`MISSING_ID`	400	IDの指定が必要
`MISSING_SLUG`	400	スラッグの指定が必要
`INVALID_CURSOR`	400	カーソルの形式が不正
`INVALID_LIMIT`	400	limit値が不正（1〜100の範囲外）
`INVALID_SORT_PARAM`	400	ソートパラメータが不正
`TOO_MANY_FILTERS`	400	フィルター条件が多すぎる（最大3件）
`TAG_FILTER_SORT_NOT_SUPPORTED`	400	タグフィルターとソートの併用は非対応

検索API固有のエラー

コード	HTTPステータス	説明
`MISSING_QUERY`	400	検索クエリが指定されていない
`QUERY_TOO_LONG`	400	検索クエリが長すぎる（500文字超）
`INVALID_SIZE`	400	size値が不正（1〜100の範囲外）
`INVALID_FROM`	400	from値が不正（負の値）
`SEARCH_WINDOW_EXCEEDED`	400	`from` + `size` が10,000件を超えている（絞り込み条件を追加してください）
`SEARCH_ERROR`	500	検索エンジンエラー

プレビュー機能のエラー

コード	HTTPステータス	説明
`INVALID_PREVIEW_TOKEN`	401	プレビュートークンが無効または期限切れ
`PREVIEW_TOKEN_TENANT_MISMATCH`	401	プレビュートークンのテナントが一致しない
`PREVIEW_TOKEN_VERIFICATION_ERROR`	401	プレビュートークンの検証エラー
`INVALID_PREVIEW_TYPE`	400	プレビュートークンの種類が不正
`CONTENT_ID_MISMATCH`	403	プレビュートークンとコンテンツIDが一致しない

問い合わせAPI固有のエラー

コード	HTTPステータス	説明
`VALIDATION_ERROR`	422	必須項目の不足・形式の誤り（`details` に項目ごとの理由が入ります）。存在しない・無効なカテゴリコードを指定した場合もこのコードになります
`server_error`	500	問い合わせの作成に失敗した

エラーハンドリングの例


async function fetchContent(id) {
  const response = await fetch(`${API_URL}/v1/cms/contents/${id}`, {
    headers: { 'X-API-Key': API_KEY },
  });
 
  if (!response.ok) {
    const body = await response.json();
 
    // 認証エラー・クレジット不足・リクエスト集中は error オブジェクトを持たない
    if (!body.error) {
      if (body.error_code === 'credit_exhausted') {
        throw new Error('クレジット残高が不足しています');
      }
      if (response.status === 429) {
        // リクエスト集中 - 間隔を空けてリトライ
        await sleep(1000);
        return fetchContent(id);
      }
      // 認証エラー - APIキーを確認
      throw new Error('APIキーを確認してください');
    }
 
    switch (body.error.code) {
      case 'NOT_FOUND':
        // コンテンツが見つからない
        return null;
      case 'FORBIDDEN':
        // 権限不足 - APIキーのパーミッションを確認
        throw new Error('APIキーの権限を確認してください');
      default:
        throw new Error(body.error.message);
    }
  }
 
  return response.json();
}