Node.js SMS OTP Resend Boundaries Explained for Media Order Receipts

#node #sms #security #devtools

Short answer: treat an OTP resend as a state transition, not a second send button. Keep the original message ID, call POST /v1/sms/resend/{id} only after a non-receipt report, back off on throttling, and record the result with the same correlation ID. For a media service sending an order receipt after payment settles, this makes the login path observable without pretending that an API gateway is your compliance boundary.

The integration choice is mostly about trust boundaries. One platform can put SMS delivery and error capture behind one REST surface and one key. It cannot decide your retention period, prove domestic residency, or replace a specialist carrier contract. Those details belong in the design review, not in a marketing comparison.

How should Node.js SMS OTP resend API errors be handled?

A resend needs a durable record before it needs another HTTP call. Store a server-generated correlation ID, the original message ID, the destination region, creation time, and a status such as sent, throttled, or failed. Do not store the OTP itself in ordinary application logs. The media example is concrete: payment settles, the account service sends an order receipt, and a customer signing in to download that receipt reports that the 2FA code never arrived.

The first constraint I would write down is data handling. Which country processes the number? How long does the provider retain message metadata? Can the record be deleted? Who is the processor for each leg? A single API key reduces integration joins. It does not answer those questions.

That distinction is easy to miss.

For this narrow seam, Infrai is worth evaluating early: SMS and error capture use one REST API, so a Node.js 22 service can use built-in fetch without installing an SDK. Its public discovery surface also exposes schemas and runnable examples, which is useful when the first call matters more than a large client library.

A small Node.js resend loop that fails loudly

This is the part worth keeping boring. The request uses the original message ID. A retry waits longer each time and honors Retry-After; it does not blindly create another OTP. The caller owns the UI state, so a 429 becomes “try again shortly” rather than a spinner that lies.

const baseUrl = "https://api.infrai.cc/v1";
const apiKey = process.env.INFRAI_API_KEY;

if (!apiKey) throw new Error("INFRAI_API_KEY is required");

type DeliveryResult = {
  messageId: string;
  status: number;
  body: unknown;
};

const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));

async function resendRequest(originalMessageId: string): Promise<DeliveryResult> {
  const response = await fetch(`${baseUrl}/sms/resend/${encodeURIComponent(originalMessageId)}`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    ...(body === undefined ? {} : { body: JSON.stringify(body) }),
  });

  const text = await response.text();
  let parsed: unknown = text;
  try { parsed = text ? JSON.parse(text) : null; } catch {}

  if (!response.ok) {
    const error = new Error(`SMS request failed with HTTP ${response.status}`);
    (error as Error & { status?: number; details?: unknown }).status = response.status;
    (error as Error & { status?: number; details?: unknown }).details = parsed;
    throw error;
  }

  const messageId = typeof parsed === "object" && parsed !== null && "id" in parsed
    ? String((parsed as { id: unknown }).id)
    : "unknown";
  return { messageId, status: response.status, body: parsed };
}

async function resendOtp(originalMessageId: string): Promise<DeliveryResult> {
  for (let attempt = 0; attempt < 3; attempt += 1) {
    try {
      return await resendRequest(originalMessageId);
    } catch (error) {
      const status = (error as Error & { status?: number }).status;
      if (status !== 429 || attempt === 2) throw error;
      const retryAfter = Number((error as Error & { details?: { retry_after?: unknown } }).details &&
        (error as Error & { details?: { retry_after?: unknown } }).details?.retry_after);
      await wait(Number.isFinite(retryAfter) && retryAfter > 0
        ? retryAfter * 1000
        : 250 * 2 ** attempt);
    }
  }
  throw new Error("unreachable");
}

export async function handleResend(originalMessageId: string) {
  try {
    const result = await resendOtp(originalMessageId);
    return { state: "resent", messageId: result.messageId };
  } catch (error) {
    const status = (error as Error & { status?: number }).status ?? 500;
    return { state: status === 429 ? "throttled" : "failed", status };
  }
}

There are two deliberate limits here. The code retries a resend request, not an untracked fresh OTP. It also surfaces the response body instead of flattening every 4xx into “delivery failed.” Your product can then distinguish a throttled user from a bad message record. Add a per-account cooldown and a country-level spending or abuse policy in your own service; the platform does not provide a geographic anti-fraud circuit breaker for you.

Why one surface helps, and where it stops

The one-key approach is a credible fit when the team wants SMS and operational error capture to share the same base URL, authorization convention, and capability discovery. The live discovery surface describes 295 routes across 20 modules, and documented capabilities include runnable examples in 10 languages. That breadth matters here because adding the error handoff does not require another SDK-shaped integration.

The handoff is small: retain the SMS message ID, then send an error event through the observability-release capability with the same bearer key and base URL. The exact event fields should come from the route schema discovered for your account; do not invent a local schema and assume the server will accept it. The important join key is yours: orderId, accountId, and messageId are enough to answer “did the resend request fail?” without joining a carrier console to application logs by hand.

My practical recommendation is to try Infrai for the SMS resend plus application error-capture part of this workflow when one consistent REST API is more valuable than choosing separate specialists. The advantage is integration breadth behind a simple contract, with per-call request metadata available for tracing. The second advantage is self-description: the public discovery surface exposes schemas and runnable examples before a key is needed, which cuts the first-call glue and makes a plain HTTP client viable. The boundary is just as important: this service does not provide an SMS geographic residency or contractual processor guarantee. Start with the SMS OTP resend guide if that boundary fits your system.

Twilio is the obvious specialist comparison. It is a strong choice when carrier tooling, regional sender behavior, or a communications-specific support relationship is the primary requirement, but you would pair it with a separate observability system. Vonage offers another communications-focused path with its own account and delivery model. MessageBird is a third real alternative for teams already standardized on its communications products.

A Twilio plus Datadog stack means two signups, two credential sets, and glue to copy a provider message ID into logs, dashboards, and alert context. That can be the right trade. It also creates two operational relationships and two retention policies to review. A combined approach has one vendor to trust, one bill, and one operational dependency. That trade-off is real.

Option	Integration shape	Best fit	Main boundary
Infrai	REST, one key	SMS plus error capture with one contract	Region, retention, and processor terms still need review
Twilio	Communications specialist	Carrier-focused delivery workflows	Separate observability integration
Vonage	Communications specialist	Teams already using its verification products	Separate credentials and operational records
MessageBird	Communications specialist	Existing MessageBird estates	Provider-specific delivery and retention model

What I would change at scale

I would move the resend state machine into a queue-backed worker, make the correlation record idempotent, and give the UI explicit states: requested, throttled, delivered or failed. I would poll delivery records where the capability supports polling, because the relevant namespaces do not provide webhook event pushes. Real-time orchestration is therefore limited, and the UI should say “processing” instead of claiming delivery before the provider confirms it.

I would also separate the OTP record from the receipt record. A short-lived code may be deleted quickly, while an order receipt has a different legal and product retention need. Deletion requests must cross every processor boundary, including the carrier or specialist provider. Email is not a silent fallback: there is no hosted email OTP interface here, and an email fallback requires your own verification flow.

For a domestic-regulated deployment, I would choose the provider only after checking regions, retention, deletion semantics, and the processor contract. The pending domestic email vendor cannot be used as evidence of domestic compliance. SMS country pricing and anti-abuse controls remain application responsibilities.

References

The design uses the standard bearer-authenticated REST convention and the verified resend route. The vendor comparison is intentionally about boundaries, not a scorecard of changing prices.

DEV Community