Retry a write without double-charging

Task

You want to retry a POST that creates a charge or an order — but a retry that actually succeeded server-side the first time would double-charge. You need the server to recognize the replay as the same logical write.

Example

One way: pair retry with an idempotency key derived from the request.

import { stitch } from 'stitchapi';

const createOrder = stitch({
    method: 'POST',
    baseUrl: 'https://api.example.com',
    path: '/orders',
    retry: { attempts: 3, on: [429, 503] },
    idempotency: {
        // body is unknown, so narrow it before reading a property.
        key: (input) => `order-${(input.body as { ref: string }).ref}`,
    },
});

const order = await createOrder({ body: { ref: 'inv-1001' } });

How it works

Each logical call carries a stable Idempotency-Key header. When retry replays the write, the server sees the same key and dedupes the side effect instead of running it twice. The default key is a random uuid generated once per call — already retry-safe; a custom key derives a stable value from the input (here the order ref) so the same logical write always maps to the same key. Idempotency only pays off alongside retries.

See also