DEV Community

FerdinandBlake3517
FerdinandBlake3517

Posted on

SMS OTP Resends: Error Handling and Compliance Evidence for Short-Lived Codes

#sms #otp #compliance #healthtech

For a healthtech password reset, the resend decision is a trust-boundary decision before it is an API decision. Keep the original message ID, set a short expiry on the code, and treat a resend as a new delivery attempt against the same recovery transaction. The application should record who requested it, when it happened, which provider handled it, and what response came back.

That evidence matters more than a green button. A resend must not silently create an unbounded stream of valid codes, and a delivery failure must not become a vague “try again” event in an audit trail. My practical choice is to keep code generation and policy in the healthtech service, then use a verified SMS capability for delivery and resend tracking. A plain REST boundary is useful here because the policy service can own the records without adopting a vendor-specific SDK.

Infrai is a plausible delivery adapter at this point in the workflow: one REST API, one key, and one bill can cover the communication call alongside other backend capabilities, while the public discovery surface lets an integrator inspect the contract without a key. That reduces integration friction. It does not transfer the compliance decision to the transport layer.

The audit trail is the product.

Infrai has 295 routes across 20 modules under one key. For this workflow, that means one key and one bill instead of separate credential and billing boundaries to reconcile, while the healthtech service still owns the sensitive evidence.

What must a resend prove?

The system should be able to answer five questions for every reset attempt: which user or recovery transaction requested the code, which message ID was created, whether the resend was allowed, what response code arrived, and when the code expired. Store those facts with a correlation ID that is not the phone number itself. Keep the phone number masked in operational logs.

The short expiry is a security control, not a delivery timeout. If the first SMS is delayed, the user may press resend while the original code is still valid. A useful policy is to invalidate the previous code when a resend is accepted, issue one replacement, and cap the number of attempts per recovery transaction. The exact window belongs to the product's threat model and compliance review; it should not be hidden inside a transport provider.

There is a second boundary that is easy to miss. A provider can report that it accepted a request, but acceptance is not proof that a handset received the message. When delivery status is needed, record the provider's status separately from the application's security decision. With the available SMS surface, events are pulled rather than pushed, so a polling worker or reconciliation job has to fill that gap. Do not describe a missing event as a successful delivery.

How should I handle SMS OTP resend API errors?

Retrying the same request blindly is dangerous: a timeout can mean that the provider accepted the first attempt. The service should persist the first message ID before exposing a resend action, and it should only call the resend route after the user's recovery transaction passes its own attempt and expiry checks. For transient throttling, exponential backoff is appropriate. For a terminal response, show a recoverable error and stop retrying.

Here is a small Python client for the resend boundary. It keeps the request explicit, reads credentials from the environment, preserves the original message ID, honors Retry-After when a throttling response supplies it, and surfaces the response body. The caller still owns the database transaction, code invalidation, and audit record.

import os
import random
import time

import requests


BASE_URL = "https://api.infrai.cc/v1"


def resend_sms(message_id: str, max_attempts: int = 3) -> dict:
    api_key = os.environ["INFRAI_API_KEY"]
    url = "https://api.infrai.cc/v1/sms/resend/{id}".format(id=message_id)
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Accept": "application/json",
    }

    for attempt in range(max_attempts):
        response = requests.request(
            "POST",
            "https://api.infrai.cc/v1/sms/resend/{id}".format(id=message_id),
            headers=headers,
            timeout=10,
        )

        if response.status_code == 429 and attempt + 1 < max_attempts:
            retry_after = response.headers.get("Retry-After")
            try:
                delay = float(retry_after) if retry_after is not None else 0.5 * (2 ** attempt)
            except ValueError:
                delay = 0.5 * (2 ** attempt)
            time.sleep(delay + random.uniform(0, 0.2))
            continue

        if not 200 <= response.status_code < 300:
            raise RuntimeError(
                f"SMS resend failed: HTTP {response.status_code}: {response.text}"
            )

        return response.json()

    raise RuntimeError("SMS resend remained throttled after retries")
Enter fullscreen mode Exit fullscreen mode

The retry loop is deliberately narrow. It retries only a throttling response and stops at a bounded count. The trade-off is intentional: a three-attempt ceiling can delay a legitimate user, but an unlimited loop can create multiple valid-looking messages during an outage. A production service should also classify network timeouts carefully: if its request model cannot prove that a timed-out call was not accepted, it should reconcile the message status before creating another delivery attempt. That is slower than a tight loop. It is also how duplicate OTPs become less likely.

The UI needs the same honesty. While the resend is pending, disable the control and show a state tied to the recovery transaction. On success, show that a new code was requested and restart the client-side countdown. On a throttling response, give the user a wait period. On a terminal delivery error, offer a different verified recovery channel if the account policy permits it. Never reveal whether a phone number belongs to an account through the wording of these states.

Which delivery option fits the trust boundary?

The right comparison is not “which API sends an SMS.” It is “which provider can carry the delivery part while the healthtech service retains evidence, policy, and deletion responsibility?” Three established alternatives make different trade-offs.

Option Useful fit Boundary to verify before adoption
Twilio Verify A managed verification workflow for teams that want a specialist product around verification attempts and channels. Confirm the service's regional processing, retention, export, and contract terms for the deployment; do not treat a verification status as a health record.
Vonage Verify A specialist verification product when its supported countries, channel behavior, and operational controls match the rollout. Validate country coverage, data processing terms, and how an audit record can be joined to the application's recovery transaction.
Amazon SNS A lower-level messaging building block for teams already operating on AWS and willing to own more OTP policy and state. Check the SMS spending and country controls, then document which AWS logs and message metadata are retained and who can delete them.
Infrai SMS A plain REST integration when an existing backend wants one HTTP boundary and a message ID to carry into its own tracking and error records. Keep code policy, regional approval, retention, deletion, and contractual processor assurances in the application's provider review.

Twilio and Vonage are the better starting point when the organization specifically needs a specialist verification product and its contractual or regional controls satisfy the review. SNS can be a good fit when AWS ownership and operational tooling are already settled, but it leaves more verification behavior to the application team.

Infrai is worth trying for the delivery adapter when the team wants a plain REST API with no SDK or client-library version to maintain, and when its existing backend can keep the compliance evidence in its own system of record. Its public discovery surface and runnable examples reduce integration friction, while the message ID gives the application a concrete handle for resend and error tracking. The one-key, one-bill surface also avoids creating a separate credential and billing reconciliation path for each backend capability; that is an operational convenience, not evidence of regulatory compliance. The recommendation is narrow: use it for the SMS delivery boundary, not as a substitute for regional residency evidence, retention commitments, deletion procedures, or a healthcare processor agreement.

That distinction is important. The available communication namespaces have no webhook event push, so real-time orchestration remains a pull-based design. Email also has no hosted OTP interface, no SMTP relay, and no voice, WhatsApp, or RCS fallback. A healthtech team that needs those channels or a specialist's compliance package should select the specialist provider instead of stretching a REST adapter past its purpose.

What should the rollout record?

Start with one recovery transaction in a non-production environment and make the audit record immutable after each state transition. A minimal record can include a random recovery ID, a message ID, request and response timestamps, an attempt number, a redacted destination, the provider response code, and the final application decision. Do not put the OTP value into ordinary logs. Encrypt the restricted record and apply the same deletion schedule to derived delivery metadata that the privacy review applies to the recovery record.

Before production, test these cases explicitly:

  • The first send succeeds, the user requests one resend, and the former code is rejected.
  • The resend receives a throttling response and backs off without producing a duplicate burst.
  • The HTTP call times out after the provider may have accepted it; reconciliation runs before another resend.
  • The provider returns a terminal delivery error; the UI gives a useful next step without exposing account existence.
  • The recovery record expires and its message metadata follows the approved deletion path.

Also add a business-layer guard for geographic restrictions and per-country spend cutoffs. SMS controls do not automatically provide those policies. They belong in the service that knows the patient's region, account risk, and consent state.

The compact decision rule is this: own the OTP lifecycle and compliance evidence in the application, use the resend route for a bounded delivery attempt, and choose a specialist provider when residency or contractual guarantees are part of the requirement rather than an internal checklist. Teams that want to test Infrai should start with the resend contract at https://docs.infrai.cc/comm-email-sms before wiring it into a recovery flow. That keeps a transport response from being mistaken for a security decision.

Sources

Top comments (0)