CallGrid API Error Codes Reference

Last Updated: August 2025
Reading Time: 5 minutes

A comprehensive guide to understanding and resolving CallGrid API error codes. This reference covers all client and server error codes you may encounter while integrating with CallGrid's call routing and bidding systems.

🚨 Client Error Codes (4000s)

Client errors indicate issues with your request or campaign configuration. These are typically resolved by adjusting your setup or contacting support.

4001 - Disabled Campaign ❌

HTTP Status: 200
Message: "Disabled"

What This Means:
Your campaign is currently disabled and cannot process calls. This typically occurs when:

• Organization ID is invalid or inactive
• Campaign ID (LCB ID) doesn't exist or has been deactivated
• Account has been suspended

How to Fix:

1. ✅ Verify your Organization ID in the CallGrid dashboard
2. ✅ Check that your Campaign ID is correct and active
3. ✅ Contact your account manager to reactivate the campaign
4. ✅ Review your account status for any billing issues

4002 - Paused Campaign ⏸️

HTTP Status: 200
Message: "Campaign is Paused"

What This Means:
The campaign has been temporarily paused by the campaign owner. This is different from a disabled campaign - it's a temporary state that can be easily resumed.

How to Fix:

1. ✅ Navigate to Campaigns in your CallGrid dashboard
2. ✅ Locate your campaign and click the Resume button
3. ✅ If you don't have dashboard access, contact support for assistance
4. ✅ Check if the pause was scheduled (e.g., outside business hours)

4003 - Invalid Caller ID 📞

HTTP Status: 200
Message: "Invalid caller ID"

What This Means:
The caller ID provided doesn't meet CallGrid's validation criteria. This protects against spam and ensures call quality.

Valid Format Examples:

• ✅ +1234567890 (E.164 format)
• ✅ +12345678901 (11-digit US number)
• ❌ 1234567890 (missing country code)
• ❌ 123-456-7890 (contains formatting)

How to Fix:

1. ✅ Ensure caller ID starts with country code (+1 for US)
2. ✅ Remove any formatting characters (spaces, dashes, parentheses)
3. ✅ Verify the number has a valid area code
4. ✅ Check that the number isn't on a blocked list

4004 - Capacity Check Failed 🚫

HTTP Status: 200
Message: "Capacity check failed"

What This Means:
The call was rejected due to capacity or filtering rules. This comprehensive error covers several scenarios:

Common Causes:

• Campaign Closed: Outside operating hours
• Daily/Monthly Cap Reached: Volume limits exceeded
• Tag Rule Failure: Call doesn't match targeting criteria
• Buyer Capacity Full: No available agents/capacity

How to Fix:

1. ✅ Check Operating Hours: Verify campaign schedule settings
2. ✅ Review Caps: Check daily/monthly volume limits in dashboard
3. ✅ Audit Tag Rules: Ensure call data matches targeting criteria
4. ✅ Monitor Buyer Capacity: Check destination availability
5. ✅ Contact Support: If settings appear correct

4005 - Duplicate Call 🔄

HTTP Status: 200
Message: "Duplicate. CallerId already paid out."

What This Means:
A call from this caller ID has already been processed and paid out within your duplicate protection window. This prevents double-charging for the same caller.

Duplicate Windows by Industry:

• Insurance: 30-90 days
• Home Services: 7-14 days
• Financial Services: 90-180 days
• Solar: 60-90 days

How to Fix:

1. ✅ This is Normal Behavior - duplicate protection is working correctly
2. ✅ Review Duplicate Settings: Adjust window if needed in campaign settings
3. ✅ Check Timestamp: Ensure the previous call was actually processed
4. ✅ Contact Support: If you believe this is an error, provide caller ID and timestamp

4006 - No Available Numbers 📵

HTTP Status: 200
Message: "No phone numbers available for PSTN."

What This Means:
There are no available phone numbers in your pool for Public Switched Telephone Network (PSTN) routing. This typically happens during high volume periods or insufficient number allocation.

How to Fix:

1. ✅ Contact Support Immediately: Request additional numbers for your pool
2. ✅ Check Number Allocation: Review current pool size vs. expected volume
3. ✅ Monitor Usage: Track peak usage patterns to prevent future shortages
4. ✅ Consider Pool Expansion: Upgrade to larger number pools for high-volume campaigns

⚡ Server Error Codes (5000s)

Server errors indicate issues on CallGrid's side or rate limiting. These are typically temporary or related to API usage patterns.

5001 - Rate Limit Exceeded ⚡

HTTP Status: 429
Message: "Rate limit exceeded"

What This Means:
Your application has made too many API requests in a short time period, exceeding CallGrid's rate limits. This protects system stability and ensures fair usage.

Default Rate Limits:

• Standard Accounts: 100 requests/minute
• Enterprise Accounts: 500+ requests/minute
• Burst Allowance: 2x rate for short periods

How to Fix:

1. ✅ Implement Backoff Strategy: Exponential backoff with retry logic
2. ✅ Reduce Request Frequency: Spread requests over longer time periods
3. ✅ Cache Responses: Avoid unnecessary repeat requests
4. ✅ Contact Support: Discuss rate limit increases for high-volume usage

Example Retry Logic:

1async function retryWithBackoff(apiCall, maxRetries = 3) {
2  for (let attempt = 1; attempt <= maxRetries; attempt++) {
3    try {
4      return await apiCall();
5    } catch (error) {
6      if (error.status === 429 && attempt < maxRetries) {
7        await new Promise(resolve => setTimeout(resolve, Math.pow(2, attempt) * 1000));
8        continue;
9      }
10      throw error;
11    }
12  }
13}
Copy

🛠️ Troubleshooting Guide

Quick Diagnostic Steps

When encountering any error code:

1. Check Error Code Pattern
   
   
2. • 4000s = Your configuration/request issue
   • 5000s = CallGrid system or rate limiting issue
2. Verify Basic Settings
   
   
3. • Campaign is active and properly configured
   • API credentials are valid and current
   • Request format matches API documentation
3. Review Recent Changes
   
   
4. • Campaign setting modifications
   • API integration updates
   • Account or billing changes

Error Resolution Priority

🔴 Immediate Action Required:

• 4001 - Disabled Campaign
• 4006 - No Available Numbers

🟡 Review and Adjust:

• 4002 - Paused Campaign
• 4004 - Capacity Check Failed

🟢 Normal Operations:

• 4005 - Duplicate Call (protection working)
• 5001 - Rate Limit (implement proper retry logic)

🔵 Data Validation:

• 4003 - Invalid Caller ID (fix data format)

📞 Getting Help

When to Contact Support

Immediate Support Needed:

• Multiple consecutive 4001 or 4006 errors
• Unexpected 4004 errors with correct configuration
• 5001 errors despite reasonable API usage

Self-Service First:

• 4002 - Check campaign status in dashboard
• 4003 - Validate caller ID format
• 4005 - Review duplicate protection settings

Support Channels

For Technical Issues:

• Email: support@callgrid.com
• Response Time: < 2 hours during business hours

For Account Issues:

• Contact: Your dedicated account manager
• Portal: CallGrid customer dashboard
• Escalation: Enterprise support for critical issues

What to Include in Support Requests

When contacting support, always include:

✅ Error Code - The specific 4-digit error code
✅ Timestamp - When the error occurred (include timezone)
✅ Request Details - API endpoint and request payload
✅ Campaign Info - Campaign ID and configuration
✅ Frequency - How often this error occurs
✅ Impact - Business impact and urgency level