How Koltrix makes send retries safe

Failed requests do not lock the key#

If a request fails before anything is queued, for example because the from address is not registered for the account or the body is invalid, the claim is released. You can fix the problem and retry with the same key immediately instead of being locked out for 24 hours by an attempt that sent nothing.

Keys are per account#

Cached responses are stored per account and key, so two different Koltrix accounts using the same key string do not collide. Within your account, reusing a key for a different message will return the first message's response, so treat keys as identifiers for one logical send.

How to choose keys#

Generate the key once, when you decide the email should exist, and reuse it for every attempt:

• A UUID stored with the record that triggered the email. For example, store receipt_email_key on the payment row when the payment succeeds, then use it for every retry of that email.
• A deterministic value derived from the business event, such as receipt- followed by the payment ID. This works even if the process that generated the key crashed before saving it.

The one thing not to do is generate a new key inside the retry loop. Every attempt would then look like a new message, and the protection disappears.

What the key does not do#

Idempotency keys protect against duplicate sends caused by retries. They are not a general deduplication system, and it helps to be clear about the edges:

• They do not compare message content. If your application calls the API twice for the same event with two different keys, perhaps because two workers both decided to send the receipt, both messages go out. Preventing that is your application's job, usually with a unique constraint on "receipt email for payment X" in your own database.
• They expire. After 24 hours a key can be used again. Retries should happen within minutes, not days, so this rarely matters, but a job that replays day-old work should not rely on old keys.
• They only apply when you send one. A request without the header is processed as a new send every time.

A retry loop that uses all four cases#

import time, uuid, requests

def send_receipt(payment, session):
    key = payment.receipt_email_key or f"receipt-{payment.id}"
    body = {
        "from": "[email protected]",
        "to": [payment.customer_email],
        "subject": "Your receipt",
        "body_text": f"We received your payment of {payment.amount_display}.",
    }
    delay = 1
    for attempt in range(6):
        try:
            r = session.post(
                "https://api.koltrix.com/api/v2/emails",
                json=body,
                headers={"Authorization": f"Bearer {KOLTRIX_KEY}", "Idempotency-Key": key},
                timeout=10,
            )
        except requests.RequestException:
            r = None
        if r is not None and r.status_code in (200, 202):
            return r.json()                    # sent, or replayed
        if r is not None and r.status_code == 429 and r.json().get("code") == "quota_exceeded":
            raise RuntimeError(f"quota exceeded until {r.json().get('resets_at')}")  # retrying won't help
        if r is not None and r.status_code < 500 and r.status_code not in (409, 429):
            raise ValueError(r.text)           # a real client error: fix the request
        time.sleep(delay)                      # timeout, 409, 429, 503 or other 5xx
        delay = min(delay * 2, 30)
    raise RuntimeError("receipt not confirmed; safe to retry later with the same key")

Key takeaways#

• Send an Idempotency-Key on every send where a duplicate would matter.
• Koltrix claims the key before queuing anything, so a retry that overlaps the original cannot send a second copy.
• 202 is a new send, 200 with Idempotent-Replayed: true is a replay, 409 means wait and retry, and 503 means nothing was sent.
• Failed requests release the key; successful responses are replayable for 24 hours.
• Generate the key once per logical message, never inside the retry loop.