Troubleshooting Guide

Troubleshooting Guide

This guide covers common issues and diagnostic procedures for the SMS Gateway Proxy platform.

Quick Health Check

Before investigating specific issues, verify the overall system state:

# 1. Check proxy health
curl http://localhost:8080/healthy
# Expected: {"status": "ok"}

# 2. Check SMPP links
curl http://localhost:8080/api/v1/dashboard/smpp-links
# Shows state of all configured SMPP connections

# 3. Check system statistics
curl http://localhost:8080/api/v1/dashboard/stats
# Shows current RPS, message counts, error rates

# 4. Check Prometheus metrics
curl http://localhost:8080/metrics
# Full metrics dump for detailed analysis

If /healthy does not return {"status": "ok"}, the proxy service itself may be down — check Docker container status with docker compose ps.

SMPP Connection Issues

Link shows "disconnected"

Symptoms: CheckESME returns persist: false, messages to this link fail.

Diagnostic steps:

1. Verify the SMSC is reachable from the proxy host:

   telnet smsc.provider.com 2775
   

2. Check link configuration in smpp_rules.toml:

   • esme_addr and esme_port — correct SMSC address?
   • esme_systemid and esme_password — correct credentials?
   • esme_disabled — is the link accidentally disabled?

3. Check Enquire Link timeouts:

   • If esme_enquirelink_timeout is too short, the proxy may disconnect from slow-responding SMSCs. Default is 40 seconds.

4. Verify network/firewall rules — the proxy needs outbound TCP access to the SMSC on the configured port.

Resolution: The proxy automatically reconnects when the SMSC becomes available. No restart is needed. If credentials were changed, update smpp_rules.toml and restart the proxy container.

All links in a pool are down

Symptoms: Pool rate limit drops to zero, all messages to this pool are rejected.

Diagnostic steps:

1. Check if the issue is on the SMSC side (all links connect to the same provider).
2. Verify network connectivity to the SMSC endpoints.
3. Check /api/v1/dashboard/smpp-links to see which specific links are affected.

Resolution: The pool will automatically recover as links reconnect. Monitor via dashboard for recovery.

Message Delivery Issues

Message not delivered (no DLR)

Diagnostic steps:

1. Check message status via API:

   curl -X POST http://localhost:8080/api/v1/sms/info \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"esme": 100, "message_id": "msg-uuid"}'
   

2. Review the status field in the response:

   • submitted — message was sent to SMSC, waiting for DLR
   • DELIVERED — successfully delivered to the recipient
   • UNDELIVERABLE — SMSC reported delivery failure
   • EXPIRED — delivery timed out

3. If the message was never submitted, check SMPP link health and rate limits.

Message rejected by contact policy

When a message is rejected by the MCP, the API response will contain a status indicating the reason. Check the state field:

High duplicate/blacklist rejection rate

If a large percentage of messages are being rejected:

1. Duplicates — review whether the sending application is accidentally resending the same messages. Check the dedup time window in MCP settings.
2. Blacklist — verify the blacklist CSV files in S3/MinIO are up to date. Check the auto-renewal schedule.
3. Contact policy — review daily/weekly limits in MCP flows. They may be set too low for the intended traffic volume.

Authentication Errors

Rate Limiting Issues

Messages rejected with HTTP 429

The client is sending faster than the configured rate limit.

Diagnostic steps:

1. Check current throughput: curl http://localhost:8080/api/v1/dashboard/stats
2. Compare with configured limits in smpp_rules.toml (esme_rate parameter)
3. Check if link health degradation has reduced the effective pool rate — see Link Health Monitoring

Resolution: Either reduce the client's sending rate or increase esme_rate / esme_rate_burst in the configuration (ensure the SMSC provider supports the higher rate).

Message Tracing

Every message processed by the proxy is assigned a UUID-based transaction ID that can be used to trace the message through the entire processing pipeline.

To trace a specific message:

1. Note the transaction_id from the send response.
2. Query the delivery status:

   curl -X POST http://localhost:8080/api/v1/sms/info \
     -H "Authorization: Bearer YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"esme": 100, "message_id": "msg-uuid"}'
   

3. The response includes: message status, per-segment delivery info, timestamps, routing information, and error details.

Useful Diagnostic Endpoints

When to Contact Support

Escalate to the platform vendor if:

• The proxy fails to start or crashes repeatedly
• Messages are submitted successfully (status submitted) but DLRs never arrive, and the SMSC provider confirms delivery
• Rate limits appear incorrect despite correct smpp_rules.toml configuration
• Redis or Aerospike connectivity issues persist after verifying network and Docker configuration

When contacting support, include: proxy version, Docker Compose configuration, smpp_rules.toml (with passwords redacted), output of /healthy, /dashboard/stats, and /dashboard/smpp-links.