Troubleshooting Common Issues

Common issues and step-by-step solutions.

Authentication Issues

401 Unauthorized

Symptoms: API returns 401 Unauthorized with error code AUTH_002 (invalid or missing API key)

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 an AUTH_004–AUTH_007 error code

Solutions:

1. AUTH_004: your API key doesn't have permission for this operation; use a key with the required access
2. AUTH_005: account onboarding is not complete; finish onboarding in the dashboard
3. AUTH_006: KYC verification is not complete; submit KYC and wait for approval
4. AUTH_007: channel setup is not complete; finish setup for the channel you're sending on
5. A suspended account also returns 403 with code BUSINESS_014; contact support

Message Sending Issues

Messages Stuck in "Queued"

Symptoms: Message status doesn't change from QUEUED

A message normally leaves QUEUED within the first few seconds after a send. If it stays queued longer:

Solutions:

1. Check KYC status is approved
2. Verify account has sufficient balance
3. Check dashboard for errors

Insufficient Balance

Symptoms: The send returns 202 Accepted, but the message is finalized as BLOCKED (insufficient balance). The status appears on GET /v3/messages/{id}/activities and arrives as a message.blocked webhook. Legacy v2 send endpoints instead return 402 with error code BUSINESS_003.

Solutions:

1. Add credits manually from Billing → Overview
2. Enable Auto Charge (Billing → Overview → gear icon) to automatically top up when your balance falls below a set threshold. This prevents the block from recurring
3. Check Billing → Billing History for failed payments

Payment failed (Auto Charge or manual top-up)

Symptoms: Red alert banner on the Dashboard reads "Your last payment didn't go through," or you received a "Your payment didn't go through" email.

Common causes:

• Card declined (insufficient funds, expired card, or bank block on off-session charges)
• No default payment method on file
• No Stripe customer record linked to the account

Solutions:

1. Go to Billing → Payment Methods and update or re-add your card
2. After updating, add credits manually to confirm the new payment method works
3. Auto Charge will resume automatically on the next trigger once a valid payment method is on file
4. If the problem persists, contact support@sent.dm with the decline reason from the email

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. Check API Status for ongoing incidents
2. Verify your account hasn't been suspended - suspended accounts also receive 403 responses with code BUSINESS_014 on API calls
3. If access still fails, email support@sent.dm with your account email and the time of the failure

Data Not Loading

Solutions:

1. Check API Status for ongoing incidents
2. Check the browser console for JavaScript errors and include them in your support ticket
3. Contact support@sent.dm if the problem persists

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