instantly-common-errors

name	instantly-common-errors
description	Diagnose and fix Instantly.ai API v2 common errors and exceptions. Use when encountering Instantly errors, debugging failed requests, or troubleshooting campaign/account/lead issues. Trigger with phrases like "instantly error", "instantly 401", "instantly 429", "instantly api failed", "instantly debug", "instantly troubleshoot".
allowed-tools	Read, Write, Edit, Bash(curl:*), Grep
version	1.12.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","instantly","debugging","errors"]
compatibility	Designed for Claude Code

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/`);

   : [] = [];

  
   (!campaign.?. || !campaign.[]?.?.) {
    issues.();
  }

  
   (!campaign.?.?.) {
    issues.();
  }

  
   mappings =  ();
   (!.(mappings) || mappings. === ) {
    issues.();
  }

  
   leads =  instantly<[]>(, {
    : ,
    : .({ : campaignId, :  }),
  });
   (leads. === ) {
    issues.();
  }

   (issues. === ) {
    .();
  }  {
    .();
    issues.( .());
  }
}