apollo-common-errors

Files (1)

• SKILL.md

SKILL.md (first lines)

# Apollo Common Errors

## Overview
Comprehensive guide to diagnosing and fixing common Apollo.io API errors with specific solutions and prevention strategies.

## Error Reference

### 401 Unauthorized

**Symptoms:**
```json
{
  "error": "Unauthorized",
  "message": "Invalid API key"
}
```

**Causes:**
1. Missing API key in request
2. Invalid or expired API key
3. API key revoked by admin
4. Wrong API key (sandbox vs production)

**Solutions:**
```bash
# Verify API key is set
echo $APOLLO_API_KEY | head -c 10

# Test API key directly
curl -s "https://api.apollo.io/v1/auth/health?api_key=$APOLLO_API_KEY" | jq

# Check key in Apollo dashboard
# Settings > Integrations > API > View/Regenerate Key
```

**Prevention:**
```typescript
// Validate API key on startup
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

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

**Causes:**
1. API feature not available in plan
2. User role doesn't have access
3. IP restriction blocking request
4. Attempting to access another account's data

**Solutions:**
```typescript
// Check plan features before calling
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

**Symptoms:**
```json
{
  "error": "Unprocessable Entity",
  "message": "q_organization_domains must be an array"
}
```

**Causes:**
1. Invalid request body format
2. Missing required fields
3. Wrong data types
4. Invalid enum values

**Common Fixes:**

```typescript
// WRONG: String instead of array
const wrong = { q_organization_domains: 'apollo.io' };

// CORRECT: Array format
const correct = { q_organization_domains: ['apollo.io'] };

// WRONG: Number instead of string
const wrong2 = { per_page: '25' };

// CORRECT: Number type
const correct2 = { per_page: 25 };
```

**Validation Helper:**
```typescript
import { z } from 'zod';

From niels-kwg/toolkit, MIT.

More from niels-kwg/toolkit