Skip to main content

Error Handling Concepts

Understanding error patterns and implementing robust error handling in your Communications API integration.

Error Response Philosophy​

The Communications API follows a specific error handling pattern designed for reliability and clarity:

  • HTTP Status Codes: Most responses return 200 OK, even for errors
  • Response Arrays: Errors are returned as arrays with detailed information
  • Multiple Error Types: Different scenarios produce different response formats
  • Descriptive Messages: Error messages provide actionable information
API-Specific Error Handling

Unlike many REST APIs, the Communications API returns 200 OK for most error scenarios, with error details in the response body. Always check the response content for error information.

Error Response Formats​

Standard Error Response​

The most common error format includes detailed information:

[
  {
    "WarningMessages": ["Descriptive error message"],
    "errorMsg": "Error description or null",
    "MessageSentId": 0,
    "MessageId": null,
    "statusMsg": null,
    "transmitDateTime": null,
    "ClientRef": null
  }
]

Key Fields:

  • WarningMessages: Array of warning/error messages
  • errorMsg: Primary error description
  • MessageId: null for failed messages, present for successful ones
  • MessageSentId: Usually 0 for errors

Success Response Pattern​

Successful messages follow a predictable pattern:

[
  {
    "WarningMessages": [],
    "errorMsg": "OK 1 messages queued for sending",
    "MessageSentId": 0,
    "MessageId": "1469.20250715.02516506506657265717-e0684dbcb71f402ab39d4d6b86d44cbb",
    "statusMsg": "In Queue",
    "transmitDateTime": "2025-07-15T17:28:54.5859378Z",
    "ClientRef": null
  }
]

Success Indicators:

  • errorMsg starts with "OK"
  • MessageId is present (not null)
  • statusMsg shows message status

Error Categories​

Authentication Errors​

Issues with credentials, permissions, or account status.

Common Patterns:

  • Invalid CustomerId or Password
  • Insufficient account permissions
  • Partner authorization issues

Response Characteristics:

  • errorMsg: "Data is not valid, no messages sent"
  • MessageId: Always null
  • WarningMessages: May contain specific permission errors

Message Content Errors​

Problems with message content, recipients, or format.

Common Patterns:

  • Invalid phone number formats
  • Message too long
  • Empty or invalid content

Response Characteristics:

  • errorMsg: Descriptive content error
  • WarningMessages: Specific validation failures

Service Errors​

System-level issues and rate limiting.

Common Patterns:

  • Server errors (HTTP 500)
  • Rate limiting
  • Service unavailability

Response Characteristics:

  • May return different HTTP status codes
  • Generic error messages for system issues

Error Handling Strategies​

1. Response Validation Pattern​

function validateResponse(response, httpStatus) {
    // Handle HTTP-level errors first
    if (httpStatus >= 500) {
        throw new Error('Server error - retry may be appropriate');
    }
    
    // Validate response format
    if (!Array.isArray(response) || response.length === 0) {
        throw new Error('Invalid response format');
    }
    
    const result = response[0];
    
    // Handle null responses
    if (result === null) {
        throw new Error('Unknown error occurred');
    }
    
    // Check for success
    if (result.errorMsg?.startsWith('OK') && result.MessageId) {
        return result; // Success
    }
    
    // Extract and handle error
    const errorMessage = result.errorMsg || 
        (result.WarningMessages?.[0]) ||
        'Unknown error';
    
    throw new Error(errorMessage);
}

2. Error Categorization​

function categorizeError(error, response) {
    const errorMsg = error.message;
    
    if (errorMsg.includes('Data is not valid')) {
        return { type: 'AUTHENTICATION', retryable: false };
    }
    
    if (errorMsg.includes('No recipients')) {
        return { type: 'INVALID_INPUT', retryable: false };
    }
    
    if (errorMsg.includes('Rate limit') || errorMsg.includes('Too many')) {
        return { type: 'RATE_LIMITED', retryable: true, backoff: true };
    }
    
    if (errorMsg.includes('Service unavailable') || error.status >= 500) {
        return { type: 'SERVICE_ERROR', retryable: true, backoff: true };
    }
    
    return { type: 'UNKNOWN', retryable: false };
}

3. Retry Logic Framework​

async function withRetry(operation, options = {}) {
    const {
        maxAttempts = 3,
        baseDelay = 1000,
        maxDelay = 10000,
        backoffMultiplier = 2
    } = options;
    
    let attempt = 0;
    let delay = baseDelay;
    
    while (attempt < maxAttempts) {
        try {
            return await operation();
        } catch (error) {
            attempt++;
            
            const errorCategory = categorizeError(error);
            
            // Don't retry non-retryable errors
            if (!errorCategory.retryable || attempt >= maxAttempts) {
                throw error;
            }
            
            // Apply backoff for appropriate errors
            if (errorCategory.backoff) {
                await new Promise(resolve => setTimeout(resolve, delay));
                delay = Math.min(delay * backoffMultiplier, maxDelay);
            }
        }
    }
}

Best Practices​

1. Defensive Programming​

  • Always validate response format before processing
  • Check for null responses which indicate unknown errors
  • Extract error messages from multiple possible locations
  • Log sufficient context for debugging

2. Error Classification​

  • Separate retriable from non-retriable errors
  • Implement appropriate backoff for service errors
  • Don't retry authentication errors
  • Handle rate limiting gracefully

3. User Experience​

  • Provide meaningful error messages to end users
  • Distinguish temporary from permanent failures
  • Offer guidance for user-correctable errors
  • Implement progress indicators for bulk operations

4. Monitoring and Alerting​

  • Track error rates by error type
  • Monitor authentication failure patterns
  • Alert on service error spikes
  • Log error context for debugging

Integration Patterns​

Circuit Breaker for Service Errors​

Prevent cascading failures by implementing circuit breaker pattern for service-level errors.

Graceful Degradation​

Design your application to handle API unavailability:

  • Queue messages for later delivery
  • Provide alternative communication channels
  • Cache successful configurations

Error Recovery​

Implement recovery mechanisms:

  • Automatic retry with exponential backoff
  • Dead letter queues for persistently failing messages
  • Manual intervention workflows for edge cases

Detailed Error References:

Related Concepts:

Detailed Error References:

Related Concepts: