API接続エラー

API接続エラー、認証失敗、統合の問題を診断して解決します。

Zenovay REST APIは有料プラン(Pro以上)で利用可能です。無料プランのキーは403 API_PAID_PLAN_REQUIREDレスポンスで拒否されます。APIキーを使用するにはアップグレードしてください。

認証エラー

"Invalid API Key" (401)

一般的な原因:

キーの形式が間違っている
- APIキーはzv_プレフィックスで始まる必要があります
- このプレフィックスのないキーは無効です
- ダッシュボードから完全なキーをコピーしたことを確認してください
キーが取り消されている
- 設定 → アカウント → セキュリティとアクセスに移動し、個人用APIキーセクションを開きます
- 既存のキーが取り消された場合は、新しいキーを作成してください
キーは1回だけ保存される
- 完全なキーは作成時にのみ表示されます。その後はプレフィックスのみが保存されます
- コピーしなかった場合は、新しいキーを作成してください

修正:

// 間違い - 無効な形式
const key = 'abc123_not_valid...';

// 正しい - Zenovay APIキー
const key = 'zv_xyz789abc...';

"API Key Not Found" (401)

ヘッダー形式を確認してください:

# 間違い
curl -H "Api-Key: zv_..."

# 正しい (外部API)
curl -H "X-API-Key: zv_..."

"API requires a paid plan" (403)

REST APIは有料機能です。無料プランで作成された(または現在バインドされている)キーは次を返します:

{
  "error": "The Zenovay API requires a paid plan. Upgrade to Pro or higher to use API keys.",
  "code": "API_PAID_PLAN_REQUIRED"
}

修正: チームをProまたはそれ以上にアップグレードしてから、設定 → アカウント → セキュリティとアクセス → 個人用APIキーでキーを作成します。

"Access denied to this website" (403)

個人用APIキーは作成時に2つのスコープを持ちます:

設定	オプション
権限	フルアクセス、または読み取り/書き込み/管理者のみ
チームアクセス	属しているすべてのチーム、または選択したチームのみ

キーはそれが行動を許可されているチーム内のWebサイトにのみアクセスできます(かつ、それらのチームのメンバーである間のみ)。特定のWebサイトで403が返される場合、それを所有するチームはキーのチームアクセスの外側にあるか、またはそのチームに属していなくなっています。設定 → アカウント → セキュリティとアクセス → 個人用APIキーでキーを確認するか、必要なアクセス権を持つキーを作成してください。

接続エラー

"Connection Refused"

エンドポイントを確認してください:

正しい: https://api.zenovay.com/api/external/v1/
間違い:  http://api.zenovay.com/api/external/v1/  (HTTPSなし)
間違い:  https://zenovay.com/api/    (ドメイン違い)

"Connection Timeout"

原因:

ネットワークの問題
ファイアウォールがブロックしている
DNS解決の失敗

デバッグステップ:

接続性をテストします:

curl -v https://api.zenovay.com/api/external/v1/usage

DNSを確認します:
```
nslookup api.zenovay.com
```
ファイアウォールを確認します:
- 発信HTTPS (443)を許可
- api.zenovay.comドメインを許可

"SSL Certificate Error"

原因:

古いルート証明書
企業プロキシの干渉
サーバーの時間のズレ

修正:

# 証明書を更新 (Ubuntu)
sudo apt update && sudo apt install ca-certificates

# システム時間を確認
date

# Node.jsを使用している場合、検証を無効にしないでください:
// DON'T DO THIS IN PRODUCTION
// process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';

レート制限エラー

"Rate Limit Exceeded" (429)

レスポンスヘッダー:

X-RateLimit-Limit: 30
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 2026-06-13T12:01:00.000Z
Retry-After: 42

APIは各レスポンスで月次使用量も返します:

X-Usage-Monthly: 4231
X-Usage-Limit: 10000

バックオフを実装します:

async function apiCallWithRetry(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status === 429) {
        const retryAfter = error.headers.get('Retry-After') || 60;
        await sleep(retryAfter * 1000);
        continue;
      }
      throw error;
    }
  }
}

REST APIレート制限

REST APIはキーごとにプランティアで制限されます。分単位のレートと月単位のリクエスト枠の両方:

プラン	分単位	月単位
Pro	30 req/min	10,000
Scale	60 req/min	100,000
Enterprise	120 req/min	1,000,000

分単位のレートを超えると429とRetry-Afterが返されます。月単位の枠を超えると429が返され、翌月初にリセットされます(X-Usage-Monthly / X-Usage-Limitヘッダーを参照)。

トラッキングと公開エンドポイントの制限

トラッキング取り込みと他の公開エンドポイントはIPごと(プランごとではない)に制限され、REST APIキー制限とは無関係です:

コンテキスト	制限
トラッキング (バースト)	60 req/10 sec per IP
トラッキング (持続)	5,000 req/hour per IP
公開エンドポイント	30 req/min per IP
認証エンドポイント	30 req/min per IP

リクエストエラー

"Bad Request" (400)

よくある問題:

無効なJSON:

// 間違い - 末尾のコンマ
{ "name": "Test", }

// 正しい
{ "name": "Test" }

クエリパラメータが不足しているか、形式が悪い:

# 間違い - 無効な日付範囲
GET /api/external/v1/analytics/{websiteId}?from=yesterday

# 正しい - ISO日付
GET /api/external/v1/analytics/{websiteId}?from=2026-06-01&to=2026-06-13

リクエストボディのデータ型が間違っている:

// 間違い - 数字の代わりに文字列
{ "page": "1" }

// 正しい
{ "page": 1 }

"Not Found" (404)

確認してください:

エンドポイントURLが正しい
リソースIDが存在する
リソースがあなたのアカウントに属している

# エンドポイントを確認 (/api/external/v1プレフィックスと複数形の「websites」に注意)
GET /api/external/v1/websites/{websiteId}  # 正しい
GET /api/external/v1/website/{websiteId}   # 間違い (単数)

"Unprocessable Entity" (422)

検証が失敗しました。レスポンスボディを確認してください:

{
  "error": "validation_error",
  "details": {
    "url": "Invalid URL format",
    "name": "Name too long (max 100 characters)"
  }
}

SDKエラー

JavaScript SDK

"Zenovay not defined":

<!-- スクリプトが読み込まれたことを確認してください -->
<script src="https://api.zenovay.com/z.js"
        data-tracking-code="YOUR_TRACKING_CODE"></script>

<!-- 読み込み後に確認してください -->
<script>
  window.addEventListener('load', () => {
    if (typeof zenovay !== 'undefined') {
      console.log('Zenovay loaded');
    }
  });
</script>

サーバーサイドAPIコール

トラッキングエンドポイントの接続問題:

// トラッキングエンドポイントでfetchを使用します - npmパッケージは不要です。
// 取り込みエンドポイントはペイロードを検証するため、完全なイベントを送信します:
// session_id (最小8文字)、絶対URL、user_agent、および
// デバイスフィールド(device_type、browser、os)はすべて必須です。
const response = await fetch('https://api.zenovay.com/e/YOUR_TRACKING_CODE', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    event_type: 'pageview',
    url: 'https://example.com/home',
    session_id: 'srv-session-abcdef',
    user_agent: 'MyServer/1.0',
    device_type: 'desktop',
    browser: 'Server',
    os: 'Linux',
  }),
});

if (!response.ok) {
  console.error('Zenovay tracking error:', response.status);
}

タイムアウトエラー:

// タイムアウト制御にAbortControllerを使用します
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 30000);

const response = await fetch('https://api.zenovay.com/e/YOUR_TRACKING_CODE', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    event_type: 'pageview',
    url: 'https://example.com/home',
    session_id: 'srv-session-abcdef',
    user_agent: 'MyServer/1.0',
    device_type: 'desktop',
    browser: 'Server',
    os: 'Linux',
  }),
  signal: controller.signal,
});

clearTimeout(timeout);

デバッグのヒント

デバッグモードを有効にする

サーバーサイドのコール:

// 外部APIコールの詳細ログを有効にします
const response = await fetch('https://api.zenovay.com/api/external/v1/websites', {
  headers: { 'X-API-Key': 'zv_...' },
});
console.log('Status:', response.status);
console.log('Response:', await response.json());

トラッキングスクリプト:

<script data-tracking-code="YOUR_TRACKING_CODE"
        data-debug="true"
        src="..."></script>

APIステータスを確認

status.zenovay.comを訪問
APIエンドポイントのステータスを確認
インシデント履歴を確認

キーアクティビティを確認

ダッシュボード:

設定 → アカウント → セキュリティとアクセスに移動し、個人用APIキーを見つけます
キーを選択してその詳細ビューを開きます
アクティビティを確認します — 過去24時間、7日間、および全期間の受け入れられたイベント数、およびキーが最後に使用された時刻

cURLでテスト

# 使用量エンドポイントでAPIキーをテスト
curl -H "X-API-Key: zv_..." \
     https://api.zenovay.com/api/external/v1/usage

# Webサイトを一覧表示
curl -H "X-API-Key: zv_..." \
     https://api.zenovay.com/api/external/v1/websites

# 詳細な出力付き
curl -v -H "X-API-Key: zv_..." \
     https://api.zenovay.com/api/external/v1/websites

よくあるエラーコード

コード	意味	解決策
400	不正なリクエスト	リクエストボディを確認
401	認証されていない	APIキーを確認
403	禁止	権限を確認
404	見つかりません	エンドポイント/IDを確認
422	検証失敗	フィールド値を確認
429	レート制限	バックオフを実装
500	サーバーエラー	再試行し、サポートに連絡
502	不正なゲートウェイ	1分後に再試行
503	利用不可	ステータスページを確認

サポートに連絡

APIの問題を報告するときは、以下を含めてください:

リクエストの詳細:
- エンドポイントURL
- HTTPメソッド
- リクエストヘッダー (APIキーは編集)
- リクエストボディ
レスポンスの詳細:
- ステータスコード
- レスポンスボディ
- レスポンスヘッダー
コンテキスト:
- タイムスタンプ
- リクエストID (ヘッダーから)
- SDKバージョン(該当する場合)

メール: [email protected]