Preventing duplicate writes during Ballerina client retries

Answer

Generate the idempotency key once, before entering the retry block, store it in a variable whose scope covers the whole retry, and attach it as a header on every attempt inside the block. Ballerina's retry mechanism re-executes the block body, but it does not reset variables declared outside it—so a key created outside the loop is naturally stable across attempts. No state-tracking wrapper object is needed; lexical scoping does the work for you.

The pattern

import ballerina/http;
import ballerina/uuid;
import ballerina/lang.value;

function createPayment(http:Client api, PaymentRequest req) returns error? {
    // 1. Generate the key ONCE, outside the retry scope.
    string idempotencyKey = uuid:createType4AsString();

    // Alternative: derive it deterministically from the logical request,
    // e.g. a hash of (accountId, amount, clientReference), so a caller-side
    // full retry of the whole operation also deduplicates.

    retry (3) {
        http:Response res = check api->post("/payments", req,
            {"Idempotency-Key": idempotencyKey});
        if res.statusCode >= 500 {
            // Force another attempt on transient server errors.
            fail error value:fromJsonStringWithType("transient failure");
        }
        // 2xx (including a replayed success from the server) ends the loop.
    }
}

Two properties make this safe:

• Stable key: the key lives outside the retry block, so attempt 1 and attempt N send the identical Idempotency-Key header.
• Server-side deduplication: the downstream service records the key and returns the original result for repeats instead of executing the write again.

What this does and does not guarantee

The likely explanation for duplicate writes in your setup is that a key (if any) is being generated inside the retry block, producing a different value per attempt, or that no key is sent at all. Moving generation outside the block fixes the first case. Confirmed facts are narrower: Ballerina retries re-run the block body, outer-scope bindings persist, and http:Client lets you set per-request headers. The language has no built-in idempotency primitive, so the header contract is entirely yours.

Important limits:

• The key only helps if the downstream service actually honors it. If the API ignores Idempotency-Key, you must deduplicate another way (unique constraints, deterministic resource IDs) or avoid retrying non-idempotent calls.
• Never reuse a key across different logical operations—colliding keys can cause the server to return the wrong prior result.
• Retry timing (backoff strategy, max attempts) varies with your Ballerina version and client configuration; verify against your installed Swan Lake release.

Verification

1. Log the key once before the retry block and inside each attempt; confirm the values match.
2. Point the client at a test endpoint that echoes request headers and forces a retry (e.g., returns 500 once); inspect that every attempt carried the same key.
3. Against a key-aware stub, confirm the second attempt returns the original success response and creates no second record.

If your downstream API documents a different deduplication header (some use X-Request-Id or a body field), substitute that name—the pattern is unchanged.