Troubleshooting

Common issues and step-by-step solutions.

Authentication Issues

401 Unauthorized

Symptoms: API returns 401 Unauthorized with error code AUTH_001

Solutions:

1. Verify your API key is correct
2. Check the x-api-key header is set (not x-sender-id - that's v2 legacy)
3. Ensure no extra whitespace in the key
4. Verify the key hasn't been revoked

# Test your API key
curl -H "x-api-key: YOUR_API_KEY" \
  https://api.sent.dm/v3/templates

403 Forbidden

Symptoms: API returns 403 Forbidden with error codes like AUTH_003

Solutions:

1. Verify KYC is complete and approved
2. Check account hasn't been suspended
3. Ensure you have permission for the requested resource

Message Sending Issues

Messages Stuck in "Queued"

Symptoms: Message status doesn't change from QUEUED

Solutions:

1. Wait 2-3 minutes (normal processing time)
2. Check KYC status is approved
3. Verify account has sufficient balance
4. Check dashboard for errors

Insufficient Balance (BUSINESS_003)

Symptoms: API returns 402 with error code BUSINESS_003

Solutions:

1. Add payment method in Billing
2. Pre-load account credits
3. Check for failed payments

429 Rate Limited (BUSINESS_002)

Symptoms: API returns 429 with error code BUSINESS_002

Rate Limits:

• Standard endpoints: 200 requests per minute
• Sensitive endpoints: 10 requests per minute

Solutions:

1. Implement exponential backoff
2. Reduce request frequency
3. Consider batching requests
4. Check rate limit headers for reset time

// Implement backoff
const retryAfter = error.headers['retry-after'] || 60;
await sleep(retryAfter * 1000);

Invalid Phone Number (VALIDATION_002)

Symptoms: Error code VALIDATION_002

Solutions:

1. Use E.164 format (+1234567890)
2. Include country code
3. Remove spaces and special characters
4. Validate before sending

function validateE164(phone: string): boolean {
  return /^\+[1-9]\d{1,14}$/.test(phone);
}

Template Issues

Template Not Found (RESOURCE_002)

Symptoms: Error code RESOURCE_002

Solutions:

1. Verify template ID is correct (use template.id in request body, not template_id)
2. Check template exists in dashboard
3. Ensure you're using the right account

Template Pending Approval

Symptoms: WhatsApp messages not sending

Solutions:

1. Wait for Meta approval (24-48 hours)
2. Use SMS in the meantime
3. Check template status
4. Review rejection reason if applicable

Template Rejected

Symptoms: Template status rejected

Solutions:

1. Review Meta's feedback
2. Fix identified issues
3. Resubmit template
4. Contact support if unclear

Webhook Issues

Webhooks Not Received

Symptoms: No webhook events arriving

Solutions:

1. Verify webhook URL is correct
2. Check endpoint returns 2xx status
3. Ensure endpoint responds within 5 seconds
4. Verify HTTPS is working
5. Check webhook is enabled in dashboard

Duplicate Webhooks

Symptoms: Same event received multiple times

Solutions:

1. Implement idempotency using event ID
2. Store processed event IDs
3. Use database transactions

See Handling Retries.

Webhook Signature Invalid

Symptoms: Signature verification fails

Solutions:

1. Use raw request body (not parsed JSON)
2. Check secret key is correct
3. Use constant-time comparison
4. Verify timestamp is recent

Channel Issues

WhatsApp Not Working

Symptoms: WhatsApp messages failing

Solutions:

1. Verify WhatsApp Business account is connected
2. Check template is approved
3. Confirm recipient has WhatsApp
4. Verify Meta Business account is in good standing

SMS Delivery Failed

Symptoms: SMS messages failing

Solutions:

1. Check phone number format
2. Verify recipient hasn't opted out
3. Check for carrier blocks
4. Review message content compliance

Performance Issues

Slow API Responses

Symptoms: API calls taking > 5 seconds

Solutions:

1. Check your network connection
2. Verify server location (use closest region)
3. Implement connection pooling
4. Check for rate limiting

High Error Rate

Symptoms: > 5% of requests failing

Solutions:

1. Check error logs for patterns
2. Review recent code changes
3. Verify API key validity
4. Check account status

Dashboard Issues

Can't Access Dashboard

Solutions:

1. Clear browser cache
2. Try incognito mode
3. Check internet connection
4. Verify account hasn't been suspended

Data Not Loading

Solutions:

1. Refresh the page
2. Check for JavaScript errors in console
3. Try different browser
4. Contact support if persistent

Debugging Steps

General Debugging Process

1. Enable debug logging

   const client = new SentDm({ logLevel: 'debug' });

2. Check request/response

   console.log('Request:', request);
   console.log('Response:', response);
   console.log('Error:', error);

3. Test in sandbox mode

   await client.messages.send({
     to: ['+1234567890'],
     template: { id: 'tmpl_123' },
     sandbox: true
   });

4. Check dashboard logs

   • Activities
   • Webhook logs

Getting Support

When contacting support, include:

1. Request ID (from meta.request_id in error response)
2. Timestamp of issue (from meta.timestamp)
3. Error code (from error.code)
4. Code snippet (remove API keys)
5. Expected vs actual behavior
6. Steps to reproduce

Email: support@sent.dm