Instantly Common Errors Skill

Instantly Common Errors

Overview

Diagnostic reference for Instantly API v2 errors. Covers HTTP status codes, campaign state errors, account health issues, lead operation failures, and webhook delivery problems.

Prerequisites

Completed instantly-install-auth setup
Access to Instantly dashboard for verification
API key with appropriate scopes

HTTP Status Codes

| Status | Meaning | Common Cause | Fix | |--------|---------|-------------|-----| | 400 | Bad Request | Malformed JSON, invalid field values | Validate request body against schema | | 401 | Unauthorized | Invalid, expired, or revoked API key | Regenerate key in Settings > Integrations | | 403 | Forbidden | API key missing required scope | Create key with correct scope (e.g., campaigns:all) | | 404 | Not Found | Invalid campaign/lead/account ID | Verify resource exists with a GET call first | | 422 | Unprocessable Entity | Business logic violation (duplicate lead, invalid state) | Check error body for details | | 429 | Too Many Requests | Rate limit exceeded | Implement exponential backoff (see below) | | 500 | Internal Server Error | Instantly server issue | Retry with backoff; check status.instantly.ai |

Campaign Errors

Campaign Won't Activate (Stuck in Draft)

// Diagnosis: check campaign requirements
async function diagnoseCampaign(campaignId: string) {
  const campaign = await instantly<Campaign>(`/campaigns/${campaignId}`);

  const issues: string[] = [];

  // Check sequences
  if (!campaign.sequences?.length || !campaign.sequences[0]?.steps?.length) {
    issues.push("No email sequences — add at least one step with subject + body");
  }

  // Check schedule
  if (!campaign.campaign_schedule?.schedules?.length) {
    issues.push("No sending schedule — add schedule with timing and days");
  }

  // Check sending accounts
  const mappings = await instantly(`/account-campaign-mappings/${campaignId}`);
  if (!Array.isArray(mappings) || mappings.length === 0) {
    issues.push("No sending accounts assigned — add via PATCH /campaigns/{id} with email_list");
  }

  // Check for leads
  const leads = await instantly<Lead[]>("/leads/list", {
    method: "POST",
    body: JSON.stringify({ campaign: campaignId, limit: 1 }),
  });
  if (leads.length === 0) {
    issues.push("No leads — add leads via POST /leads");
  }

  if (issues.length === 0) {
    console.log("Campaign looks ready to activate");
  } else {
    console.log("Issues preventing activation:");
    issues.forEach((i) => console.log(`  - ${i}`));
  }
}

Campaign Status Codes

| Status | Label | Meaning | |--------|-------|---------| | 0 | Draft | Not yet activated | | 1 | Active | Currently sending | | 2 | Paused | Manually paused | | 3 | Completed | All leads processed | | 4 | Running Subsequences | Main sequence done, subsequences active | | -1 | Accounts Unhealthy | Sending accounts have SMTP/IMAP errors | | -2 | Bounce Protect | Auto-paused due to high bounce rate | | -99 | Suspended | Account-level suspension |

Fix: Accounts Unhealthy (-1)

async function fixUnhealthyAccounts(campaignId: string) {
  // 1. Get accounts assigned to campaign
  const accounts = await instantly<Account[]>("/accounts?limit=100");

  // 2. Test vitals for each
  const vitals = await instantly("/accounts/test/vitals", {
    method: "POST",
    body: JSON.stringify({ accounts: accounts.map((a) => a.email) }),
  });

  // 3. Identify and fix broken accounts
  for (const v of vitals as any[]) {
    if (v.smtp_status !== "ok" || v.imap_status !== "ok") {
      console.log(`BROKEN: ${v.email} — SMTP=${v.smtp_status}, IMAP=${v.imap_status}`);
      // Pause the broken account
      await instantly(`/accounts/${encodeURIComponent(v.email)}/pause`, { method: "POST" });
      console.log(`  Paused ${v.email}. Fix credentials, then resume.`);
    }
  }
}

Lead Errors

Duplicate Lead (422)

// Prevent duplicates by setting skip flags
await instantly("/leads", {
  method: "POST",
  body: JSON.stringify({
    campaign: campaignId,
    email: "user@example.com",
    first_name: "Jane",
    skip_if_in_workspace: true,   // skip if email exists anywhere in workspace
    skip_if_in_campaign: true,    // skip if already in this campaign
  }),
});

Lead Status Reference

| Status | Label | Description | |--------|-------|-------------| | 1 | Active | Eligible to receive emails | | 2 | Paused | Manually paused | | 3 | Completed | All sequence steps sent | | -1 | Bounced | Email bounced | | -2 | Unsubscribed | Lead unsubscribed | | -3 | Skipped | Skipped (blocklist, duplicate, etc.) |

Rate Limit Handling

async function withBackoff<T>(
  operation: () => Promise<T>,
  maxRetries = 5
): Promise<T> {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await operation();
    } catch (err: any) {
      if (err.status === 429 && attempt < maxRetries) {
        const wait = Math.pow(2, attempt) * 1000;
        console.warn(`429 Rate Limited. Waiting ${wait}ms (attempt ${attempt + 1}/${maxRetries})`);
        await new Promise((r) => setTimeout(r, wait));
        continue;
      }
      throw err;
    }
  }
  throw new Error("Unreachable");
}

Webhook Errors

| Issue | Diagnostic | Fix | |-------|-----------|-----| | Events not delivered | Check webhook status: GET /webhooks | Webhook may be paused — resume with POST /webhooks/{id}/resume | | Wrong event format | Compare to expected schema | Ensure event_type matches: email_sent, reply_received, etc. | | Delivery failures | Check GET /webhook-events/summary | Fix target URL, ensure 2xx response within 30s | | Retries exhausting | Instantly retries 3x in 30s | Return 200 immediately, process async |

Quick Diagnostic Script

set -euo pipefail
echo "=== Instantly Health Check ==="

# Test auth
curl -s -o /dev/null -w "Auth: HTTP %{http_code}\n" \
  https://api.instantly.ai/api/v2/campaigns?limit=1 \
  -H "Authorization: Bearer $INSTANTLY_API_KEY"

# Count campaigns by status
curl -s https://api.instantly.ai/api/v2/campaigns?limit=100 \
  -H "Authorization: Bearer $INSTANTLY_API_KEY" | \
  jq 'group_by(.status) | map({status: .[0].status, count: length})'

# Check account health
curl -s https://api.instantly.ai/api/v2/accounts?limit=100 \
  -H "Authorization: Bearer $INSTANTLY_API_KEY" | \
  jq '[.[] | {email, status, warmup_status}] | .[:5]'

Error Handling

| Error | Cause | Solution | |-------|-------|----------| | 401 after key rotation | Old key cached | Restart app / clear env cache | | 403 on campaign activate | Missing campaigns:update scope | Regenerate API key with correct scopes | | 422 duplicate lead | Lead already in workspace | Use skip_if_in_workspace: true | | Campaign -2 bounce protect | Bounce rate >5% | Clean lead list, verify emails before import | | Warmup health dropping | Too many campaign emails too soon | Reduce daily_limit, extend warmup period |

Resources

Next Steps

For structured debugging, see instantly-debug-bundle.

Agent Skills: Instantly Common Errors

Install this agent skill to your local

Skill Files