API Error Codes and Troubleshooting Guide

Understanding API Errors

The Coext External API uses a consistent error format across all endpoints. Understanding these errors will help you build robust integrations that handle failures gracefully.

Standard Error Response Format

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description of the error",
    "details": {
      // Additional context (varies by error type)
    }
  },
  "meta": {
    "request_id": "req_abc123def456ghi789"
  }
}
            

Key Fields:

• success: Always false for errors
• error.code: Machine-readable error identifier (use this for programmatic handling)
• error.message: Human-readable description
• error.details: Additional context specific to the error type
• meta.request_id: Unique ID for this request (helpful for support)

Authentication Errors (HTTP 401)

These errors occur when the API cannot verify your identity.

Example: INVALID_API_KEY Error

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid"
  },
  "meta": {
    "request_id": "req_xyz789"
  }
}
            

Permission Errors (HTTP 403)

These errors occur when your API key doesn’t have the required permissions.

Required Permissions by Endpoint

Rate Limiting Errors (HTTP 429)

These errors occur when you exceed your API usage limits.

Rate Limit Error Response

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please wait before making more requests.",
    "details": {
      "retry_after": 45
    }
  },
  "meta": {
    "request_id": "req_rate123",
    "rate_limit": {
      "limit": 60,
      "remaining": 0,
      "reset_at": "2025-12-19T10:01:00.000Z"
    }
  }
}
            

Implementing Rate Limit Handling

async function sendWithRateLimitHandling(payload) {
  const response = await fetch(url, options);
  
  if (response.status === 429) {
    const data = await response.json();
    const retryAfter = data.error?.details?.retry_after || 60;
    
    console.log(`Rate limited. Waiting ${retryAfter} seconds...`);
    await sleep(retryAfter * 1000);
    
    // Retry the request
    return sendWithRateLimitHandling(payload);
  }
  
  return response;
}

function sleep(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}
            

Validation Errors (HTTP 400)

These errors occur when your request data is invalid or incomplete.

Validation Error with Field Details

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": {
      "fields": {
        "to": "Phone number must be in E.164 format (e.g., +919876543210)",
        "message": "Message is required and cannot be empty"
      }
    }
  },
  "meta": {
    "request_id": "req_val456"
  }
}
            

Message Delivery Errors (HTTP 400/500)

These errors occur during message sending or delivery.

WhatsApp-Specific Error Codes

When messages fail through WhatsApp, you’ll receive specific error codes from Meta:

WhatsApp Error Response Example

{
  "success": false,
  "error": {
    "code": "MESSAGE_SEND_FAILED",
    "message": "Failed to send message",
    "details": {
      "whatsapp_error_code": 131047,
      "whatsapp_error_message": "Re-engagement message required. Outside 24-hour customer service window."
    }
  },
  "meta": {
    "request_id": "req_wa789"
  }
}
            

Server Errors (HTTP 500/503)

Implementing Robust Error Handling

Comprehensive Retry Logic

async function sendMessageWithRetry(payload, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await sendMessage(payload);
      
      if (response.success) {
        return response;
      }
      
      const errorCode = response.error?.code;
      
      // Don't retry client errors (except rate limits)
      if (!shouldRetry(errorCode)) {
        throw new ApiError(errorCode, response.error?.message);
      }
      
      // Handle rate limits specially
      if (errorCode === 'RATE_LIMIT_EXCEEDED') {
        const retryAfter = response.error?.details?.retry_after || 60;
        await sleep(retryAfter * 1000);
        continue;
      }
      
      // Exponential backoff for other retryable errors
      const delay = Math.pow(2, attempt) * 1000;
      console.log(`Retry attempt ${attempt} after ${delay}ms`);
      await sleep(delay);
      
    } catch (error) {
      if (attempt === maxRetries) {
        throw error;
      }
    }
  }
  
  throw new Error('Max retries exceeded');
}

function shouldRetry(errorCode) {
  const retryableCodes = [
    'RATE_LIMIT_EXCEEDED',
    'INTERNAL_ERROR',
    'SERVICE_UNAVAILABLE'
  ];
  return retryableCodes.includes(errorCode);
}
            

Error Code Switch Handler

function handleApiError(error) {
  const code = error.code;
  const details = error.details;
  
  switch (code) {
    case 'INVALID_API_KEY':
    case 'EXPIRED_API_KEY':
    case 'REVOKED_API_KEY':
      console.error('Authentication failed - check your API credentials');
      // Alert operations team
      break;
    
    case 'PERMISSION_DENIED':
      console.error('Missing permission - update API key settings');
      break;
    
    case 'RATE_LIMIT_EXCEEDED':
      console.warn(`Rate limited. Retry after ${details?.retry_after}s`);
      // Queue for delayed retry
      break;
    
    case 'INVALID_PHONE_NUMBER':
      console.error('Bad phone number format');
      // Mark contact as invalid
      break;
    
    case 'MESSAGE_SEND_FAILED':
      const waCode = details?.whatsapp_error_code;
      if (waCode === 131047 || waCode === 130472) {
        console.log('24-hour window closed - need template message');
        // Switch to template sending
      }
      break;
    
    default:
      console.error(`Unhandled error: ${code}`);
  }
}
            

HTTP Status Code Quick Reference

Getting Help

If you encounter persistent errors that you can’t resolve:

1. Note the request_id from the error response
2. Check the Webhook Logs in the dashboard for delivery issues
3. Review API Key permissions and status
4. Verify template configuration if using templates
5. Contact support with the request_id and error details