Juicebox 一般的なエラー

概要

Juicebox API の一般的なエラーを診断および解決するためのクイックリファレンスです。

エラーリファレンス

認証エラー

401 Unauthorized

Error: Invalid or expired API key
Code: AUTHENTICATION_FAILED

原因:

• API キーが正しくない
• API キーが失効している
• 環境変数が設定されていない

解決方法:

# API キーが設定されているか確認
echo $JUICEBOX_API_KEY

# curl でテスト
curl -H "Authorization: Bearer $JUICEBOX_API_KEY" \
  https://api.juicebox.ai/v1/auth/verify

403 Forbidden

Error: Insufficient permissions for this operation
Code: PERMISSION_DENIED

原因:

• API キーに必要なスコープがない
• アカウント階層の制限
• プランで利用不可な機能

解決方法:

• ダッシュボードで API キーのアクセス権限を確認
• 必要に応じてアカウント階層をアップグレード
• アクセス権限についてサポートに連絡

レート制限エラー

429 Too Many Requests

Error: Rate limit exceeded
Code: RATE_LIMITED
Retry-After: 60

原因:

• 1 分あたりのリクエスト数を超過
• 日次クォータを超過
• バースト制限に達した

解決方法:

// 指数バックオフを実装
async function withBackoff(fn: () => Promise<any>, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.code === 'RATE_LIMITED') {
        const delay = error.retryAfter * 1000 || Math.pow(2, i) * 1000;
        await sleep(delay);
        continue;
      }
      throw error;
    }
  }
}

検索エラー

400 Bad Request - 無効なクエリ

Error: Invalid search query syntax
Code: INVALID_QUERY
Details: Unexpected token at position 15

原因:

• クエリの構文が正しくない
• フィールド名が無効
• クォートが閉じられていない

解決方法:

// 送信前にクエリを検証
function validateQuery(query: string): boolean {
  const openQuotes = (query.match(/"/g) || []).length;
  if (openQuotes % 2 !== 0) return false;

  const openParens = (query.match(/\(/g) || []).length;
  const closeParens = (query.match(/\)/g) || []).length;
  if (openParens !== closeParens) return false;

  return true;
}

404 Profile Not Found

Error: Profile with ID 'xxx' not found
Code: NOT_FOUND

原因:

• プロファイル ID が無効
• プロファイルが削除されている
• キャッシュ参照が古い

解決方法:

• プロファイル ID の形式を確認
• 見つからない場合を適切に処理
• キャッシュ無効化を実装

ネットワークエラー

ETIMEDOUT

Error: Request timed out
Code: TIMEOUT

解決方法:

// 大規模な検索のためタイムアウトを増加
const client = new JuiceboxClient({
  apiKey: process.env.JUICEBOX_API_KEY,
  timeout: 60000 // 60 秒
});

診断コマンド

# API ステータスを確認
curl https://status.juicebox.ai/api/status

# 接続性を確認
curl -I https://api.juicebox.ai/v1/health

# 認証をテスト
curl -H "Authorization: Bearer $JUICEBOX_API_KEY" \
  https://api.juicebox.ai/v1/auth/me

エラーハンドリングパターン

try {
  const results = await juicebox.search.people(query);
} catch (error) {
  if (error.code === 'RATE_LIMITED') {
    // 再試行のためキューに追加
  } else if (error.code === 'INVALID_QUERY') {
    // クエリ構文を修正
  } else if (error.code === 'AUTHENTICATION_FAILED') {
    // 認証情報を更新
  } else {
    // ログに記録して通知
    logger.error('Juicebox error', { error });
  }
}

リソース

• エラーコード リファレンス
• ステータスページ

次のステップ

エラーを解決した後は、診断情報の収集については juicebox-debug-bundle を参照してください。