Diagnose and fix common Apollo.io API errors.
Use when encountering Apollo API errors, debugging integration issues,
or troubleshooting failed requests.
Trigger with phrases like "apollo error", "apollo api error",
"debug apollo", "apollo 401", "apollo 429", "apollo troubleshoot".
Diagnose and fix common Apollo.io API errors.
Use when encountering Apollo API errors, debugging integration issues,
or troubleshooting failed requests.
Trigger with phrases like "apollo error", "apollo api error",
"debug apollo", "apollo 401", "apollo 429", "apollo troubleshoot".
allowed-tools
Read, Grep, Bash(curl:*)
version
1.13.0
license
MIT
author
Jeremy Longshore <jeremy@intentsolutions.io>
tags
["saas","apollo","api","debugging"]
compatibility
Designed for Claude Code, also compatible with Codex and OpenClaw
Apollo Common Errors
Overview
Comprehensive guide to diagnosing and fixing Apollo.io API errors. Apollo uses x-api-key header authentication and the base URL https://api.apollo.io/api/v1/. Apollo distinguishes between master and standard API keys — many endpoints require master keys.
// Most common cause: missing x-api-key header or wrong key formatasyncfunctiondiagnoseAuth() {
try {
const response = awaitfetch('https://api.apollo.io/api/v1/auth/health', {
headers: { 'x-api-key': process.env.APOLLO_API_KEY! },
});
const data = await response.json();
if (data.is_logged_in) {
console.log('API key is valid');
} else {
console.error('API key is invalid or expired');
console.error(' Generate a new one at: Apollo > Settings > Integrations > API Keys');
}
} catch (err: any) {
console.error('Cannot reach Apollo API:', err.message);
}
}
Common 401 causes:
Using api_key query parameter instead of x-api-key header
Key was revoked or regenerated in the dashboard
Key has trailing whitespace (check with echo -n "$APOLLO_API_KEY" | wc -c)
Step 3: Handle 403 — Wrong Key Type
Standard API key: search + enrichment only
Master API key: full access (contacts, sequences, deals, tasks)
Endpoints that require a master key:
POST /contacts (create/update)
POST /emailer_campaigns/search (sequences)
POST /emailer_campaigns/{id}/add_contact_ids
POST /opportunities (deals)
POST /tasks (tasks)
DELETE /contacts/{id}
// Diagnose: test a master-key-only endpointasyncfunctiondiagnoseMasterKey() {
try {
await client.post('/contacts/search', { per_page: 1 });
console.log('Master API key confirmed');
} catch (err: any) {
if (err.response?.status === 403) {
console.error('Your API key is a standard key. Master key required.');
console.error(' Go to Apollo > Settings > Integrations > API Keys');
console.error(' Generate a new key with "Master Key" type');
}
}
}
Step 4: Handle 429 — Rate Limiting
Apollo uses fixed-window rate limiting per endpoint category:
Endpoint Category | Limit | Window | Burst
--------------------------+------------+---------+------
People Search | 100/min | 1 min | 10/sec
People Enrichment | 100/min | 1 min | 10/sec
Bulk People Enrichment | 10/min | 1 min | 2/sec
Organization Enrichment | 100/min | 1 min | 10/sec
Contacts (CRUD) | 100/min | 1 min | 10/sec
Sequences | 100/min | 1 min | 10/sec
