Troubleshooting Guide

Authentication Errors

"Invalid or expired API key"

Causes:

• API key was deleted or deactivated

• API key has expired

• Incorrect key format

Solutions:

1. Verify key starts with sk_live_ or sk_test_

2. Check key expiration date in dashboard

3. Create a new API key if needed

"API key does not have permission"

Cause: Key lacks required permissions

Solution:

1. Go to Settings → API Keys

2. Check key permissions

3. Update permissions or create new key with correct permissions

WhatsApp Errors

"Template not found"

Causes:

• Template name misspelled

• Template not approved yet

• Template deleted from Meta

Solutions:

1. List templates: GET /api/whatsapp/templates?workspaceId={id}&status=APPROVED

2. Check template status in Meta Business Manager

3. Wait for approval (24-48 hours for marketing templates)

"WhatsApp credentials not found"

Cause: WhatsApp not connected to workspace

Solution:

1. Go to Settings → Integrations

2. Click "Connect WhatsApp"

3. Complete embedded signup flow

"Message outside 24-hour window"

Cause: Trying to send regular message after 24 hours

Solution: Use template messages instead:

POST /api/conversations/{id}/send-template
{
  "templateName": "follow_up",
  "languageCode": "en"
}

Bulk Send Errors

"Maximum 1000 recipients per request"

Solution: Split your campaign:

// Split into chunks of 1000
const chunks = [];
for (let i = 0; i < recipients.length; i += 1000) {
  chunks.push(recipients.slice(i, i + 1000));
}

// Send each chunk
for (const chunk of chunks) {
  await fetch('/api/whatsapp/bulk-send', {
    body: JSON.stringify({
      recipients: chunk,
      ...otherParams
    })
  });
}

"Variable mismatch"

Cause: Template has variables but CSV doesn't

Example:

Template: "Hello {{1}}, your code is {{2}}"
CSV: phone,name (missing second variable)

Solution: Ensure CSV has all required columns

Webhook Errors

"Invalid signature"

Causes:

• Wrong secret key

• Payload modified

• Encoding mismatch

Solution:

// Verify signature EXACTLY like this
const crypto = require('crypto');

function verifyWebhook(rawBody, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(rawBody); // Use raw body, not parsed JSON!
  const expected = hmac.digest('hex');
  return signature === expected;
}

// Express.js - use raw body
app.post('/webhooks',
  express.json({ verify: (req, res, buf) => {
    req.rawBody = buf.toString();
  }}),
  (req, res) => {
    const isValid = verifyWebhook(
      req.rawBody,
      req.headers['x-icecore-signature'],
      process.env.WEBHOOK_SECRET
    );
    // ...
  }
);

Webhook Timeouts

Cause: Your endpoint takes > 10 seconds

Solution:

1. Process webhooks asynchronously

2. Return 200 immediately

3. Process in background job

app.post('/webhooks', (req, res) => {
  // Respond immediately
  res.status(200).send('OK');
  
  // Process async
  processWebhook(req.body).catch(console.error);
});

Webhooks Not Received

Check:

1. URL is publicly accessible (not localhost)

2. HTTPS (not HTTP)

3. Firewall allows incoming requests

4. Webhook is active: GET /api/webhooks?workspaceId={id}

Rate Limit Issues

"Rate limit exceeded"

Response Headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1635724800
Retry-After: 45

Solution: Implement exponential backoff:

async function apiCallWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);
    
    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After') || 60;
      await sleep(retryAfter * 1000);
      continue;
    }
    
    return response;
  }
  throw new Error('Max retries exceeded');
}

CSV Upload Issues

"No valid recipients found"

Common mistakes:

• Column header must be exactly phone or phone_number

• Phone numbers missing + prefix

• Empty rows in CSV

Solution: Validate CSV format:

phone,name,company
+77001234567,Aibek,TechCorp
+77007654321,Samat,StartupInc

"Failed to parse CSV"

Causes:

• Special characters in data

• Inconsistent columns per row

• BOM (Byte Order Mark) at start

Solution:

1. Save CSV as UTF-8 without BOM

2. Ensure all rows have same number of columns

3. Escape commas in data with quotes: "Company, Inc"

Performance Issues

Slow API Responses

Solutions:

1. Use pagination (limit=20 instead of fetching all)

2. Cache responses client-side

3. Use webhooks instead of polling

4. Filter by date range (days=7 vs days=365)

Bulk Send Takes Too Long

Expected: ~1 minute per 1,000 messages

Optimization:

• We batch in groups of 20 (250ms between batches)

• This is optimal for WhatsApp rate limits

• Larger batches may trigger WhatsApp blocking

Database Connectivity

"Failed to connect to database"

Temporary issue: Retry after 5 seconds

Persistent issue:

1. Check status page: https://status.icecore.ai

2. Contact support if incident ongoing

Getting Help

Before Contacting Support

1. Check this guide for common issues

2. Review API logs in your webhook delivery logs

3. Test with Postman to isolate client code issues

4. Verify credentials are correct

Contact Support

Email: support@icecore.ai

Include:

• Request ID (from error response)

• Timestamp of issue

• Full error message

• Sample request (remove sensitive data!)

Response time:

• Critical issues: 2-4 hours

• Normal issues: 24 hours

• Feature requests: 48-72 hours

Still stuck? → support@icecore.ai