Error Handling

All eCommunicate API errors follow a consistent JSON format with standard HTTP status codes. This guide covers the error response structure, common error scenarios, and delivery failure codes.

Every error response contains four fields:

{
  "status": "ERROR",
  "message": "Description of what went wrong",
  "requestId": "c3a1f8e2-4b6d-11ee-be56-0242ac120002",
  "timestamp": "2026-01-15T10:30:00Z"
}

The most common error. Check these causes:

When a message is accepted (202) but fails to deliver, the failure is reported via webhooks (in the statusUpdateURL payload) or the Message Reports API.

Use this decision tree when a message fails:

1. Check the HTTP status code

   • 4xx → Fix the request (see scenarios above)
   • 5xx → Retry with exponential backoff
   • 202 → Message was accepted; check delivery status below

2. Check delivery status via webhook or Message Reports API

   • DELIVERED / READ → Success
   • FAILED → Check failureCode and failureReason

3. Check the failure code

   • Codes 4, 54 → Phone number issue
   • Codes 22, 23 → Recipient blocked/blacklisted
   • Codes 59, 60 → WhatsApp Lite connection issue
   • Codes 130xxx → Meta Cloud API issue
   • Codes 132xxx → Template issue

4. If still stuck → Contact support@ecommunicate.co.za with the requestId

For transient errors (429, 500, 502, 503), implement exponential backoff:

async function sendWithRetry(payload, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      const response = await sendMessage(payload);
      if (response.status === 429 || response.status >= 500) {
        throw new Error(`HTTP ${response.status}`);
      }
      return response;
    } catch (error) {
      if (attempt === maxRetries) throw error;
      const delay = Math.min(1000 * Math.pow(2, attempt), 30000);
      console.log(`Retry ${attempt + 1} in ${delay}ms: ${error.message}`);
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}