How Do I Handle RCS Message Delivery Failures?

Handling RCS Delivery Failures: Complete Guide

Delivery failures are inevitable. Here's how to handle them properly.

Common Failure Reasons

Invalid Phone Numbers:

• Number doesn't exist
• Number is disconnected
• Number is formatted incorrectly
• Country code missing or wrong

Carrier Blocks:

• Number on carrier blocklist
• Recipient reported previous message as spam
• Carrier filtering based on content
• Regulatory blocks (region-specific)

Device Limitations:

• Device doesn't support RCS
• RCS disabled in settings
• Out of data coverage
• Phone is off or out of range

Template Issues:

• Template not approved by carrier
• Template content violates policy
• Rich media file too large
• Invalid URL or broken link

Compliance Issues:

• Recipient opted out
• Missing opt-in consent
• Regulatory violation (GDPR, TCPA, etc.)
• Age or geographic restriction

Technical Errors:

• API authentication failure
• Rate limit exceeded
• Server timeout
• Network connectivity issue

Error Codes and Meanings

400 Bad Request:

• Invalid phone number format
• Missing required parameters
• Invalid template ID
• Malformed request body

401 Unauthorized:

• Invalid or expired API key
• Missing authentication header
• Wrong API endpoint

403 Forbidden:

• API key doesn't have permission
• Brand verification revoked
• Template not approved

404 Not Found:

• Invalid message ID
• Template doesn't exist
• Contact not found

429 Too Many Requests:

• Rate limit exceeded
• Need to slow down sending
• Implement backoff

500 Internal Server Error:

• Provider server issue
• Retry with exponential backoff

503 Service Unavailable:

• Temporary outage
• Retry after delay

Retry Logic Strategy

When to retry:

• 5xx errors (server issues) - YES, always retry
• 429 rate limits - YES, after delay
• Network timeouts - YES, retry
• 400 bad request - NO, fix request first
• 401 unauthorized - NO, check auth
• 403 forbidden - NO, check permissions
• 404 not found - NO, resource doesn't exist

Exponential backoff:

Attempt 1: Immediate
Attempt 2: Wait 1 second
Attempt 3: Wait 2 seconds
Attempt 4: Wait 4 seconds
Attempt 5: Wait 8 seconds
Give up: After 5 attempts

Implementation example:

def send_with_retry(message, max_attempts=5):
    for attempt in range(max_attempts):
        try:
            return api.send(message)
        except RateLimitError:
            wait = 2 ** attempt
            time.sleep(wait)
        except ServerError:
            wait = 2 ** attempt
            time.sleep(wait)
        except (BadRequest, Unauthorized, Forbidden):
            break  # Don't retry these
    
    # All retries failed, try SMS fallback
    return sms_fallback.send(message)

Automatic SMS Fallback

How it works:

1. Attempt RCS delivery
2. If RCS fails or device doesn't support RCS
3. Automatically send via SMS instead
4. Use simplified message content (no rich media)
5. Track which path was used for analytics

Fallback message format:

• Strip images, videos, carousels
• Keep core text and CTA
• Shorten to fit SMS character limits
• Include short URL if needed
• Maintain sender ID and branding

Example: RCS: "Hi Sarah, your cart is waiting! Image of products Shop now: Button" SMS: "Hi Sarah, your cart is waiting! Shop now: https://ex.co/cart123 STOP to opt out"

Suppression Lists

What to suppress:

• Numbers that hard-bounced (don't exist)
• Numbers that opted out
• Numbers that complained (spam reports)
• Invalid phone numbers
• Numbers on Do Not Call lists

How to maintain:

• Add to suppression list immediately on hard failure
• Sync across all systems
• Check before every send
• Retain indefinitely
• Honor across all campaigns and brands

Suppression list sync:

• Daily sync between RCS platform and CRM
• Real-time sync for opt-outs
• Weekly sync with email suppression
• Quarterly review and cleanup

Monitoring and Alerting

Key metrics to monitor:

• Delivery rate (target: >95%)
• Failure rate (alert if >5%)
• SMS fallback rate (track trend)
• Error code distribution
• Retry success rate

Alerts to set up:

• Delivery rate drops below 90%
• Specific error code spikes
• Provider API errors
• SMS fallback rate suddenly increases
• Carrier-specific delivery issues

Example alerts:

IF delivery_rate < 90% for 1 hour
  ALERT: "RCS delivery rate degraded"

IF error_code_429 > 100 per minute
  ALERT: "Rate limit issues - reduce sending speed"

IF sms_fallback_rate > 50%
  ALERT: "High fallback rate - check RCS availability"

Feedback Loops

Carrier feedback loops:

• Carriers notify you of spam complaints
• Automatically suppress complainers
• Required for maintaining good standing
• Typically processed within 24-48 hours

What to do with feedback:

• Remove complained numbers from active lists
• Add to suppression list permanently
• Review message content that triggered complaint
• Adjust targeting or content if pattern emerges

Logging and Debugging

What to log:

• Every message send attempt
• Delivery status updates
• Error codes and messages
• Retry attempts
• Fallback to SMS
• Webhook events
• Timestamp for all events

Log format example:

{
  "timestamp": "2024-12-20T14:23:45Z",
  "message_id": "msg_abc123",
  "recipient": "+1234567890",
  "status": "delivered",
  "channel": "rcs",
  "attempt": 1,
  "error_code": null,
  "carrier": "verizon"
}

Log retention:

• Keep detailed logs for 30-90 days
• Archive summary logs for 1-2 years
• Required for compliance audits
• Useful for debugging patterns

Common Failure Patterns and Solutions

Pattern 1: High failure rate for specific country code

• Cause: Regulatory blocks or limited carrier support
• Solution: Segment by country, adjust strategy

Pattern 2: Sudden spike in 429 errors

• Cause: Rate limit exceeded
• Solution: Implement throttling, request limit increase

Pattern 3: Specific template has high failure rate

• Cause: Template violates policy or has broken content
• Solution: Review template, get re-approved, fix content

Pattern 4: SMS fallback rate suddenly increases

• Cause: RCS outage or device compatibility issue
• Solution: Monitor carrier status, adjust expectations

Pattern 5: Delivery succeeds but engagement is zero

• Cause: Wrong audience or message timing
• Solution: Review targeting and send time

Testing Failure Scenarios

Test these scenarios in sandbox:

1. Invalid phone number format
2. Non-existent phone number
3. Opted-out recipient
4. Rate limit exceeded
5. Template not approved
6. Carrier network timeout
7. Device doesn't support RCS (triggers fallback)
8. Network connectivity issues

Verify your code handles:

• Each error code correctly
• Retry logic works as expected
• SMS fallback activates when needed
• Suppression list is updated
• Alerts trigger appropriately

Provider-Specific Considerations

Different providers handle failures differently:

• Some have more aggressive retry logic
• Some have better SMS fallback integration
• Some provide better error messages
• Some have different rate limits

When evaluating providers, ask:

• What's your retry logic?
• How do you handle SMS fallback?
• What error codes do you return?
• Do you have feedback loops with carriers?
• What's your typical delivery rate?

The Bottom Line

Delivery failures are normal and expected. The key is handling them gracefully:

1. Implement smart retry logic with exponential backoff
2. Automatic SMS fallback for unsupported devices
3. Maintain clean suppression lists
4. Monitor delivery metrics and alert on issues
5. Log everything for debugging
6. Test failure scenarios in sandbox
7. Set up feedback loops with carriers

A well-designed failure handling system ensures your messages reach customers reliably while maintaining good standing with carriers and compliance with regulations.

Need help designing your error handling strategy? I can review your current implementation and recommend improvements for reliability and compliance.