Apollo よくあるエラー

概要

Apollo.io APIのよくあるエラーを診断・修正するための包括的なガイドです。具体的なソリューションと予防戦略を提供します。

エラーリファレンス

401 Unauthorized（認可されていません）

症状:

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

原因:

1. リクエストにAPIキーが含まれていない
2. 無効または期限切れのAPIキー
3. 管理者によってAPIキーが無効化された
4. 誤ったAPIキー（サンドボックス vs 本番環境）

ソリューション:

# APIキーが設定されていることを確認
echo $APOLLO_API_KEY | head -c 10

# APIキーを直接テスト
curl -s "https://api.apollo.io/v1/auth/health?api_key=$APOLLO_API_KEY" | jq

# Apolloダッシュボードでキーを確認
# Settings > Integrations > API > View/Regenerate Key

予防:

// スタートアップ時にAPIキーを検証
async function validateApiKey() {
  try {
    await apollo.healthCheck();
    console.log('Apollo API key valid');
  } catch (error) {
    console.error('Invalid Apollo API key - check APOLLO_API_KEY');
    process.exit(1);
  }
}

---

403 Forbidden（禁止されています）

症状:

{
  "error": "Forbidden",
  "message": "You don't have permission to access this resource"
}

原因:

1. APIの機能がプランで利用できない
2. ユーザーロールがアクセス権限を持っていない
3. IP制限がリクエストをブロックしている
4. 他のアカウントのデータへのアクセスを試みている

ソリューション:

// 呼び出し前にプランの機能を確認
const PLAN_FEATURES = {
  basic: ['people_search', 'organization_enrich'],
  professional: ['sequences', 'bulk_operations'],
  enterprise: ['advanced_search', 'custom_fields'],
};

function checkFeatureAccess(feature: string, plan: string): boolean {
  return PLAN_FEATURES[plan]?.includes(feature) ?? false;
}

---

422 Unprocessable Entity（処理できないエンティティ）

症状:

{
  "error": "Unprocessable Entity",
  "message": "q_organization_domains must be an array"
}

原因:

1. リクエストボディの形式が無効
2. 必須フィールドが不足している
3. データ型が間違っている
4. 無効な列挙値

よくある修正:

// 誤り: 文字列の代わりに配列
const wrong = { q_organization_domains: 'apollo.io' };

// 正: 配列形式
const correct = { q_organization_domains: ['apollo.io'] };

// 誤り: 文字列の代わりに数値
const wrong2 = { per_page: '25' };

// 正: 数値型
const correct2 = { per_page: 25 };

バリデーションヘルパー:

import { z } from 'zod';

const PeopleSearchSchema = z.object({
  q_organization_domains: z.array(z.string()).optional(),
  person_titles: z.array(z.string()).optional(),
  page: z.number().int().positive().default(1),
  per_page: z.number().int().min(1).max(100).default(25),
});

function validateSearchParams(params: unknown) {
  return PeopleSearchSchema.parse(params);
}

---

429 Too Many Requests（リクエストが多すぎます - レート制限）

症状:

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please retry after 60 seconds."
}

レート制限:

エンドポイント	制限	ウィンドウ
People Search	100 req/分	1 分
Enrichment	100 req/分	1 分
Sequences	50 req/分	1 分
Bulk Operations	10 req/分	1 分

ソリューション - 指数バックオフ:

class RateLimitHandler {
  private retryAfter = 0;
  private retryCount = 0;
  private maxRetries = 5;

  async executeWithRetry<T>(fn: () => Promise<T>): Promise<T> {
    while (this.retryCount < this.maxRetries) {
      try {
        if (this.retryAfter > 0) {
          await this.wait(this.retryAfter);
          this.retryAfter = 0;
        }
        return await fn();
      } catch (error: any) {
        if (error.response?.status === 429) {
          this.retryAfter = this.parseRetryAfter(error.response);
          this.retryCount++;
          console.warn(`Rate limited, retry ${this.retryCount} after ${this.retryAfter}ms`);
        } else {
          throw error;
        }
      }
    }
    throw new Error('Max retries exceeded');
  }

  private parseRetryAfter(response: any): number {
    const retryHeader = response.headers['retry-after'];
    if (retryHeader) {
      return parseInt(retryHeader) * 1000;
    }
    return Math.pow(2, this.retryCount) * 1000; // Exponential backoff
  }

  private wait(ms: number): Promise<void> {
    return new Promise(resolve => setTimeout(resolve, ms));
  }
}

---

500 Internal Server Error（内部サーバーエラー）

症状:

{
  "error": "Internal Server Error",
  "message": "An unexpected error occurred"
}

原因:

1. Apolloサービスの障害
2. リクエストの形式が不正でサーバーエラーが発生
3. 複雑なクエリでタイムアウト

ソリューション:

# Apolloのステータスを確認
curl -s https://status.apollo.io/api/v2/status.json | jq '.status.description'

# クエリを簡略化して再試行
curl -X POST "https://api.apollo.io/v1/people/search" \
  -H "Content-Type: application/json" \
  -d '{"api_key": "'$APOLLO_API_KEY'", "page": 1, "per_page": 1}'

---

結果が空の場合

症状:

{
  "people": [],
  "pagination": { "total_entries": 0 }
}

原因:

1. フィルターが厳しすぎる
2. 無効なドメインまたは会社名
3. Apolloデータベースに一致するデータがない

診断ステップ:

async function diagnoseEmptyResults(criteria: any) {
  // 各フィルターを個別にテスト
  const tests = [
    { name: 'domain', params: { q_organization_domains: criteria.domains } },
    { name: 'titles', params: { person_titles: criteria.titles } },
    { name: 'location', params: { person_locations: criteria.locations } },
  ];

  for (const test of tests) {
    if (test.params[Object.keys(test.params)[0]]) {
      const result = await apollo.searchPeople({ ...test.params, per_page: 1 });
      console.log(`${test.name}: ${result.pagination.total_entries} results`);
    }
  }
}

---

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

// src/lib/apollo/error-handler.ts
import { AxiosError } from 'axios';

export class ApolloErrorHandler {
  handle(error: AxiosError): never {
    const status = error.response?.status;
    const data = error.response?.data as any;

    switch (status) {
      case 401:
        throw new ApolloAuthError(
          'Invalid API key. Verify APOLLO_API_KEY is set correctly.'
        );
      case 403:
        throw new ApolloPermissionError(
          `Permission denied: ${data?.message || 'Check your plan features'}`
        );
      case 422:
        throw new ApolloValidationError(
          `Invalid request: ${data?.message}`,
          data?.errors
        );
      case 429:
        throw new ApolloRateLimitError(
          'Rate limit exceeded',
          this.parseRetryAfter(error)
        );
      case 500:
        throw new ApolloServerError(
          'Apollo server error. Check status.apollo.io'
        );
      default:
        throw new ApolloError(
          `Apollo API error: ${status} - ${data?.message || error.message}`
        );
    }
  }

  private parseRetryAfter(error: AxiosError): number {
    return parseInt(error.response?.headers['retry-after'] || '60');
  }
}

リソース

• Apollo API Error Codes
• Apollo Status Page
• Apollo Support

次のステップ

デバッグエビデンス収集については apollo-debug-bundle に進んでください。