CallGrid API Error Codes Reference

Last Updated: January 2026
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 (Grid 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. Contact support if you receive this message.

4007 – Caller ID Blocked ⛔

HTTP Status: 200
Message: "CallerId Blocked"

What This Means:
The caller ID has been explicitly blocked by platform-level controls or campaign rules.

Common Causes:

• Caller appears on a blocked or suppression list
• Fraud, spam, or compliance-related restrictions
• Manual block applied by an administrator

How to Fix:

• ✅ Review blocked caller lists in the dashboard
• ✅ Verify the caller ID is not flagged for abuse
• ✅ Contact support if the block appears incorrect

4008 – Duplicate Bid 🧾

HTTP Status: 200
Message: "Duplicate bid for CallerId"

What This Means:
A bid request was submitted more than once for the same caller ID within the bid de-duplication window.

How to Fix:

• ✅ Ask the campaign admin of the Grid ID to enable "Allow repeat pings" in their Bidding Settings.

4009 – Failed Tag Rules 🏷️

HTTP Status: 200
Message: "Failed tag rules"

What This Means:
The incoming call or bid did not satisfy one or more campaign tag-based targeting rules.

Common Causes:

• Missing required tags
• Tag values outside accepted ranges (wrong State, ZipCode, etc).
• Mismatched geography, intent, or vertical

How to Fix:

• ✅ Validate all required tags are included in the request
• ✅ Confirm tag formats and value ranges
• ✅ Review campaign targeting logic in the dashboard

⚡ 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. These rate limits are set by the customer.

Default Per Source Rate Limits:

• Enterprise Accounts: 500 requests/minute
• The organization can choose to allow a higher request limit for your Source by overriding your rate limit on the Source tab of their Campaign. Either slow down your requests to this Grid ID, or contact the campaign admin and ask them to increase the rate limit.

🛠️ Troubleshooting Guide

Quick Diagnostic Steps

When encountering any error code:

1. Check Error Code Pattern
2. • 4000s = Your configuration/request issue
   • 5000s = Grid ID 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