Idempotency

Why it matters

Without an idempotency key, a request that times out and is retried sends twice and is charged twice. The client never learns whether the first attempt succeeded, because the timeout tells you nothing about what the server did.

This is not a rare edge case. Mobile networks drop connections, load balancers time out, and every sensible HTTP client retries. On a payment OTP that means the customer gets two codes and you pay for both; on a campaign it can mean a duplicate blast to the whole list.

How to use it

curl -X POST https://api.sendozi.com/v1/sms/send \
  -H "Authorization: Bearer $SENDOZI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-48291-otp" \
  -d '{
    "sender": "Sendozi",
    "recipient": "+2348012345678",
    "message": "Your code is 492811. Valid for 10 minutes.",
    "sms_type": "transactional"
  }'

What happens on a repeat

• Keys are scoped to your workspace, so two customers cannot collide.
• Keys are retained for 24 hours. After that the same key is a fresh request.
• A rejected request releases its key, which is what makes 'fix the input and retry with the same key' safe.

Choosing a key

Derive the key from your own identifier for the thing being sent - an order id, a verification attempt id, a campaign id. A random value generated per retry defeats the entire mechanism, because each retry looks like a new request.

async function sendWithRetry(payload: SendPayload, idempotencyKey: string, attempts = 3) {
  for (let attempt = 1; attempt <= attempts; attempt += 1) {
    try {
      const response = await fetch("https://api.sendozi.com/v1/sms/send", {
        method: "POST",
        headers: {
          Authorization: `Bearer ${process.env.SENDOZI_API_KEY}`,
          "Content-Type": "application/json",
          // The SAME key on every attempt. That is the whole point.
          "Idempotency-Key": idempotencyKey,
        },
        body: JSON.stringify(payload),
      });

      const body = await response.json();
      if (body.success) return body.data;

      // Permanent failures will fail identically next time.
      if (response.status < 500 && body.error?.code !== "rate_limit_exceeded") {
        throw new Error(`${body.error.code}: ${body.error.message}`);
      }
    } catch (error) {
      if (attempt === attempts) throw error;
    }

    await new Promise((resolve) => setTimeout(resolve, 2 ** attempt * 250));
  }
}

// Key derived from the business event, stable across retries.
await sendWithRetry(payload, `order-${order.id}-shipped`);

What not to retry

Idempotency makes a retry safe; it does not make one useful. These errors will return the same result however many times you try, and retrying them wastes your rate limit:

• invalid_request, invalid_recipient - fix the payload.
• sender_id_not_approved, kyc_required, channel_not_active - a gate, not a glitch.
• insufficient_balance - fund the wallet first.
• recipient_suppressed - the recipient opted out.
• idempotency_conflict - you reused a key with different content.

Retry 5xx responses, network timeouts, and rate_limit_exceeded after the delay named in its resolution. Back off exponentially, and cap the attempts.