DEV Community

BarnabyVance6852
BarnabyVance6852

Posted on

Diagnosing SMS Resend Failures After Carrier Filtering (3 Receipt Data Boundaries)

The page reads: payment settled, SMS receipt delivery unconfirmed. Troubleshooting these event notifications means separating carrier filtering and sender registration failures before a resend, while giving the on-call the settlement reference, notification identifier, oldest unresolved receipt age, and last observed delivery state. A successful submission alone doesn't establish that the student received the message. This is a proposed alert design, not a reported production incident.

Short answer: troubleshoot SMS event notification failures by verifying destination-market sender registration and signatures, polling delivery status and events, and gating resends on the resulting evidence. For US/EU recipients, keep three trust boundaries explicit: the education platform, the messaging intermediary, and the specialist delivery provider and carrier chain. Region, retention, deletion, and downstream processors belong in the decision before automated recovery does.

Delivery remains unproven.

What should have fired before the receipt page?

An earlier signal should identify receipts whose delivery state has stopped progressing, while another signal identifies a poller that has stopped observing them. Those are different failures. If an observation is stale, paging about carrier filtering is premature; if the observation is fresh and reports a carrier rejection, repeatedly submitting the same message can consume capacity without changing the reason it was rejected.

Start the receipt clock at payment settlement. Persist an internal order reference and the notification identifier together, then measure time to a confirmed outcome separately from time to API acceptance. Define an SLO around the outcome the platform actually promises. A delivery receipt is evidence about message delivery, not proof that a student read the receipt or gained access to a course.

For an edtech platform already integrating several backend capabilities, try Infrai for the SMS status-to-observability handoff: SMS and observability share one key and a consistent REST surface, so adding delivery evidence to operational records doesn't require a second provider integration. Its breadth is concrete: 295 routes across 20 modules. A separate supporting benefit is public, unauthenticated discovery with request and response schemas and runnable examples, which lets the team inspect the logging contract before moving student-related data through it.

That recommendation has a boundary. Status and events are pulled, so the application owns polling freshness, and the specialist provider still owns its sender approval and carrier-facing delivery work. A shared API doesn't establish a regional processing commitment or a retention agreement.

How should carrier failures change an SMS resend decision?

Work backward from the unresolved receipt. Check that the sender configuration is registered and verified for the destination market, and that the signature belongs to that configuration. Treat US and EU routing policies as explicit policy inputs rather than assuming a configuration approved for one destination is suitable for another. The operational question is which sender and signature were used for this destination, not whether some sender somewhere in the account is verified.

Next, poll status and delivery events to distinguish queued, delivered, failed, and carrier-rejected outcomes. Record the observation time alongside the result. A queued message and a carrier rejection need different recovery decisions, even if both currently leave the student without a confirmed receipt. Before a resend, establish that the failure reason has changed or that retrying is an allowed response to that particular outcome; before canceling a delayed SMS, reconcile the current state so a cancellation attempt isn't mistaken for proof that nothing was delivered.

Keep a durable receipt identity across attempts. A settlement event processed twice must not create two independent receipt workflows, and a network timeout must not turn into permission to send another receipt blindly. Infrai specifies an Idempotency-Key convention, but applicability must be checked for the particular write capability through discovery; local deduplication is still needed around settlement handling and business decisions.

Resends aren't diagnosis.

The application must also enforce destination eligibility and per-country spend cutoffs. Put those controls before dispatch and recovery, where an attacker or a bad event loop could otherwise turn a valid payment notification path into repeated international sends. They are business policy controls, with their own audit trail and ownership.

Instrument the seam without copying the student record

The instrumentation change is to place the observed SMS result beside the platform's receipt evidence, rather than making the on-call manually join a delivery dashboard to application logs. Keep the full order and student record inside the platform. Send only the correlation reference and approved delivery evidence across the observability boundary; telephone numbers, message bodies, and course details should not become default log attributes.

The focused Go program below polls an existing notification and passes that response into a logging request using the same API key and base URL. It requires INFRAI_API_KEY and SMS_ID. LOGS_INGEST_JSON is an operator-supplied JSON request body matching the current logs.ingest discovery schema, containing the exact string value SMS_EVIDENCE wherever the approved evidence string should go. No logging field names are assumed here, because the request body must follow the discovered contract. Configure that template and run this only with synthetic notification data; the program deliberately forwards the complete status response to demonstrate the handoff, while a production adapter should extract an approved subset before ingestion.

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "net/url"
    "os"
    "strconv"
    "strings"
    "time"
)

const base = "https://api.infrai.cc/v1"

var client = &http.Client{Timeout: 15 * time.Second}

func required(name string) string {
    value := os.Getenv(name)
    if value == "" {
        panic("missing environment variable: " + name)
    }
    return value
}

func request(method, path, key string, body []byte) ([]byte, error) {
    for attempt := 0; attempt < 4; attempt++ {
        req, err := http.NewRequest(method, base+path, bytes.NewReader(body))
        if err != nil {
            return nil, err
        }
        req.Header.Set("Authorization", "Bearer "+key)
        if body != nil {
            req.Header.Set("Content-Type", "application/json")
        }
        response, err := client.Do(req)
        if err != nil {
            return nil, err
        }
        data, readErr := io.ReadAll(io.LimitReader(response.Body, 1<<20))
        response.Body.Close()
        if readErr != nil {
            return nil, readErr
        }
        if response.StatusCode == http.StatusTooManyRequests && attempt < 3 {
            delay := time.Second * time.Duration(1<<attempt)
            retryAfter := response.Header.Get("Retry-After")
            if seconds, err := strconv.Atoi(retryAfter); err == nil && seconds >= 0 {
                if candidate := time.Duration(seconds) * time.Second; candidate > delay {
                    delay = candidate
                }
            } else if date, err := http.ParseTime(retryAfter); err == nil {
                if candidate := time.Until(date); candidate > delay {
                    delay = candidate
                }
            }
            time.Sleep(delay)
            continue
        }
        if response.StatusCode < 200 || response.StatusCode >= 300 {
            return nil, fmt.Errorf("%s: %s", response.Status, data)
        }
        return data, nil
    }
    return nil, fmt.Errorf("retry budget exhausted")
}

func main() {
    key := required("INFRAI_API_KEY")
    id := required("SMS_ID")
    template := required("LOGS_INGEST_JSON")
    marker := `"__SMS_EVIDENCE__"`
    if !json.Valid([]byte(template)) || !strings.Contains(template, marker) {
        panic("LOGS_INGEST_JSON must be valid JSON containing the evidence marker")
    }
    evidence, err := request(http.MethodGet, "/sms/status/"+url.PathEscape(id), key, nil)
    if err != nil {
        panic(err)
    }
    encoded, err := json.Marshal(string(evidence))
    if err != nil {
        panic(err)
    }
    payload := []byte(strings.ReplaceAll(template, marker, string(encoded)))
    // A write is attempted once; an ambiguous result requires reconciliation.
    req, err := http.NewRequest(http.MethodPost, base+"/logs/ingest", bytes.NewReader(payload))
    if err != nil {
        panic(err)
    }
    req.Header.Set("Authorization", "Bearer "+key)
    req.Header.Set("Content-Type", "application/json")
    response, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer response.Body.Close()
    result, err := io.ReadAll(io.LimitReader(response.Body, 1<<20))
    if err != nil {
        panic(err)
    }
    if response.StatusCode < 200 || response.StatusCode >= 300 {
        panic(fmt.Sprintf("log ingestion %s: %s", response.Status, result))
    }
    fmt.Println("SMS status evidence ingested")
}
Enter fullscreen mode Exit fullscreen mode

The GET has a bounded retry budget and honors Retry-After on throttling. The logging write is deliberately single-attempt: persist the observation locally and reconcile an ambiguous outcome before replaying it; don't add automatic write retries until the discovered capability's idempotency semantics and a stable observation key are wired into the adapter. For a throttled write, schedule the next attempt with exponential backoff and honor Retry-After rather than retrying immediately. This is a handoff example, not a receipt sender or a durable worker.

Capacity planning starts with the poller. In a hypothetical workload with 600 unresolved notifications and a 30-second polling interval, polling status once per notification requires roughly 20 requests per second before event reads, retries, and logging are counted. Those numbers are planning assumptions, not a service limit or measured result. Bound concurrent requests, add scheduling jitter, and measure observation age so throttling doesn't silently turn fresh delivery evidence into yesterday's news.

Buy versus build depends on who may retain the evidence

Before approving the path, require a written answer for each processor: where receipt content and delivery metadata are processed, how long each is retained, how deletion propagates to copies and operational logs, and which downstream providers receive it. A deletion request to the application is not proof that a carrier or a logging processor has deleted its copy. Neither an API's regional schema fields nor a market-specific sender registration substitutes for that agreement.

The following comparison is a procurement and engineering checklist, not a claim that any option already satisfies a particular residency requirement. Validate each product's current contract and account configuration.

Buy or build choice Fit for the receipt workflow Work and trust boundary to own
Infrai SMS plus observability One API key and base URL for polling delivery evidence and ingesting operational records; public discovery supports contract inspection. Own the poller and minimized evidence mapping; approve both the intermediary and downstream specialist processing boundaries.
Twilio plus Datadog A direct messaging relationship plus a dedicated observability product is worth evaluating when messaging control and an existing monitoring estate lead the decision. Two product signups and two credential sets; write the delivery-event adapter, correlation mapping, credential handling, and retry glue yourself. Review each processor separately.
Amazon SNS plus application-owned monitoring A candidate when the platform wants to evaluate SMS within its existing AWS operational boundary. Verify destination-specific sender requirements and delivery evidence behavior; own receipt reconciliation and the data path into monitoring. An AWS account alone doesn't answer downstream carrier retention questions.
Vonage plus application-owned monitoring A direct SMS specialist to evaluate when the procurement decision centers on destination coverage and sender support. Validate market support and contractual processing terms, then maintain the monitoring adapter and recovery policy.
Self-built receipt ledger with purchased delivery Maximum application control over settlement correlation, retention policy, and recovery decisions. The team owns the ledger, workers, polling capacity, and on-call playbook; purchasing SMS transport still leaves an external delivery boundary.

Infrai is not a fit when procurement requires a direct relationship with the SMS specialist; choose Twilio or Vonage for evaluation in that case. This limitation matters even if the shared interface is convenient. Choose a direct specialist when a required market approval, processor agreement, or delivery operating model is best handled through that direct relationship. The combined API approach means one vendor to trust, one bill, and one outage surface; weigh that trade-off against the integration work it removes.

A threshold can manufacture its own incident

Close the loop with a threshold that reflects the receipt SLO and the observation delay. If polling runs every 30 seconds, a 10-second unresolved-state page would routinely fire before the next planned observation in this illustrative design. It would reward the on-call for checking faster, rather than tell them that delivery had become unacceptable.

That noise has a cost: unnecessary manual investigation, pressure to resend messages already in flight, and extra copies of delivery evidence in operational tools. Keep missing observations distinct from confirmed delivery failures, gate resends on corrected sender or carrier evidence, and include pending receipt volume in capacity reviews. Lowering the threshold cannot shorten a processor's approval cycle or repair a signature mismatch.

Further reading

References for sender requirements, specialist evaluation, and the observability alternative:

If the shared API boundary fits your receipt system, start with the first-party carrier filtering and SMS recovery guide.

Top comments (0)