Insertion Sort is the algorithm Python’s Timsort uses for arrays under 64 elements. Not just a teaching tool — it’s in production in the world’s most popular runtime.

🃏 The Core Idea

Pick up playing cards one by one. Each new card gets inserted into the correct position among the cards already in your hand — comparing right to left until it finds its spot.

📋 Example: [5, 3, 8, 1, 4]

• Take 3 → shift 5 → insert → [3, 5, 8, 1, 4]
• Take 8 → 8 > 5, no shift → [3, 5, 8, 1, 4]
• Take 1 → shift 8, 5, 3 → insert at start → [1, 3, 5, 8, 4]
• Take 4 → shift 8, 5 → insert after 3 → [1, 3, 4, 5, 8] ✅

💻 Code

Python

def insertion_sort(arr):
    for i in range(1, len(arr)):
        key = arr[i]
        j = i - 1
        while j >= 0 and arr[j] > key:
            arr[j + 1] = arr[j]
            j -= 1
        arr[j + 1] = key
    return arr

JavaScript

function insertionSort(arr) {
  for (let i = 1; i < arr.length; i++) {
    let key = arr[i], j = i - 1;
    while (j >= 0 && arr[j] > key) {
      arr[j + 1] = arr[j];
      j--;
    }
    arr[j + 1] = key;
  }
  return arr;
}

⏱ Complexity

🆚 Full Comparison

🏭 Why Used in Real Systems?

• Nearly sorted data → near-linear performance
• Small arrays → beats O(n log n) due to lower overhead
• Online algorithm → sorts a stream as data arrives

Part 9 of the Bitveen DSA Series. Full series at bitveen.com

Originally published at bitveen.com

I remember the exact moment I nearly choked on my coffee.

I was staring at my OpenAI bill for March 2026. $1,247. For what? A bunch of chat completions, some image analysis, and a few streaming responses. My side project was literally bleeding money.

Then a buddy sent me a screenshot of his DeepSeek V4 Flash costs. $31. Same month. Same workload.

That was the day I went down the rabbit hole of alternative AI models and how to actually use them without rewriting my entire codebase.

The Numbers That Made Me Switch

Heres the raw math. I’m not gonna sugarcoat it. If you’re using GPT-4o right now, you’re probably paying way too much.

• GPT-4o: $2.50 per million input tokens, $10.00 per million output tokens. That’s the baseline.
• DeepSeek V4 Flash (via Global API): $0.18 input, $0.25 output. That’s 40× cheaper. I had to triple-check that.
• Qwen3-32B: $0.18 input, $0.28 output. Also crazy cheap.
• DeepSeek V4 Pro: $0.57 input, $0.78 output. Still 12.8× cheaper than GPT-4o.
• GLM-5: $0.73 input, $1.92 output. 5.2× cheaper but still great for certain tasks.
• Kimi K2.5: $0.59 input, $3.00 output. 3.3× cheaper.

Do the math: if you’re spending $500/month on OpenAI, you could be spending around $12.50. That’s not a typo. $12.50.

But Is the Quality Actually Good?

Honestly? I was skeptical too. I’ve been burned by “cheaper alternatives” before. You know the ones — models that can barely write a coherent email.

But DeepSeek V4 Flash? It’s genuinely impressive. On most of my benchmarks (coding, reasoning, summarization) it matches or beats GPT-4o. For my use case — generating product descriptions and analyzing customer emails — it’s basically indistinguishable.

And Qwen3-32B? That thing is a beast for multilingual stuff. I occasionally need to handle Japanese and Korean text, and it crushes it.

So the quality is there. The price is definitely there. The only question is: how hard is it to switch?

The Migration That Took 30 Seconds

I’m not kidding. I literally changed two lines of code. Two.

Here’s my Python setup before:

from openai import OpenAI

client = OpenAI(api_key="sk-xxxxxxxxxx")

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
    temperature=0.7,
    max_tokens=500,
)

And here’s after:

from openai import OpenAI

client = OpenAI(
    api_key="ga_xxxxxxxxxxxx",
    base_url="https://global-apis.com/v1"
)

response = client.chat.completions.create(
    model="deepseek-chat",  # that’s all I changed
    messages=[{"role": "user", "content": "Hello!"}],
    temperature=0.7,
    max_tokens=500,
)

Yep. The SDK is the same. The parameters are the same. The response object is the same. I just swapped the API key and base URL, and changed the model name.

I even tested it with streaming — works perfectly.

stream = client.chat.completions.create(
    model="deepseek-chat",
    messages=[{"role": "user", "content": "Write a haiku about cheap APIs"}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")

And I’ve tested it in Node.js too. Same pattern: change apiKey and baseURL in the OpenAI SDK. Done.

What Works and What Doesn’t

I’m gonna be real with you. Not every feature from OpenAI is available. But the core stuff? All good.

• Chat completions — yes, identical.
• Streaming — yes, SSE works.
• Function calling — yes, same format.
• JSON mode — yes, just set response_format.
• Vision / image inputs — yes, supported by models like Qwen-VL and DeepSeek-VL.
• Embeddings — coming soon, I hear.
• Fine-tuning — not available. But honestly? Most indie hackers don’t need it. If you do, you probably want to spin up your own infrastructure anyway.
• Assistants API — not available. Build your own state machine, it’s not that hard.
• TTS / STT — not available. Use a dedicated service like ElevenLabs or Whisper.

For my projects, I only needed chat completions with streaming and a little bit of vision. Global API covers that perfectly.

The Only Real Downside

You’re not locked into one ecosystem. But is that a downside? Honestly, I like having choice. I can switch between DeepSeek, Qwen, GLM, Kimi with just a model name change. If one goes down or gets worse, I just update one string.

The only thing I miss is the OpenAI “playground” where you can test models interactively. But I just fire up a quick Python script or use the Global API dashboard. No big deal.

Why I’m Never Going Back

My API bill went from $1,247 to $33.42 the next month.

I used the savings to rent a decent GPU instance and experiment with my own fine-tuned model — for fun. Plus I bought myself a nice monitor with the leftover.

For context, my app processes about 200,000 requests per month. With GPT-4o, that was costing me arm and leg. With DeepSeek V4 Flash, it’s pocket change.

And the migration was the easiest technical decision I’ve made all year.

One More Example — Just to Prove It

Here’s a quick curl example if you’re into that sort of thing:

curl https://global-apis.com/v1/chat/completions 
  -H "Authorization: Bearer ga_xxxxxxxxxxxx" 
  -H "Content-Type: application/json" 
  -d '{
    "model": "deepseek-chat",
    "messages": [{"role": "user", "content": "What is 2+2?"}]
  }'

That returns the same JSON structure as OpenAI. My logging and error handling didn’t need any changes.

The Bottom Line

If you’re an indie hacker, a startup founder, or just someone who got tired of paying GPT-4o prices — switch. It’s stupidly easy.

Just change your base_url to https://global-apis.com/v1, grab a key from Global API, and pick a model that costs pennies.

I’m not saying you should never use OpenAI. If you absolutely need the latest and greatest frontier model for a specific benchmark, fine. But for 99% of real-world applications? DeepSeek V4 Flash is more than enough.

Check out Global API if you want to start saving. It’s honestly the best thing I’ve done for my projects this year. Your wallet will thank you.

Look, let me spill the beans right up front: I’m obsessed with saving money. Not in a cheap-skate way—more like a “why pay $3.00 per million tokens when you can get 80 tok/s for $0.15?” kind of way. Here’s the thing: when I started building AI-powered apps last year, I thought speed was everything. But after digging into the numbers with Global API, I realized that latency and cost are deeply intertwined. Check this out—I ran a full benchmark on 15 models, focusing not just on Time to First Token (TTFT) and tokens per second, but on what those numbers mean for your wallet.

In this guide, I’ll break down exactly how I optimized my costs using real data from May 2026. I tested every model from multiple regions, and I’m sharing the raw results—every $/M figure, every millisecond, every surprise. By the end, you’ll see how I cut my API spending by nearly 92% while still keeping response times under 200ms.

The Setup: Instruments and All That

Before I dive into the savings, let me walk you through how I gathered this data. I used Global API (https://global-apis.com/v1) for everything because it gives me access to all these models under one roof. Here’s my exact setup:

• Test Date: May 20, 2026
• Test Regions: US East (Ohio) and Asia (Singapore)
• Test Prompt: “Explain recursion in 200 words”
• Output Tokens: ~150 tokens per test
• Iterations: 10 runs, averaged
• Streaming: Yes (SSE)
• API Base: https://global-apis.com/v1

I chose “Explain recursion” because it’s a classic that forces models to think while generating. The results? Mind-blowing. But let’s start with the numbers that made me do a double-take.

The Big Reveal: Speed vs. Cost — The Ultimate Tradeoff

Here’s the raw data from my benchmarks, sorted by tokens per second. But pay attention to the $/M column—that’s where the real story lives.

Notice how reasoning models (R1, K2.5, K2-Thinking) include internal thinking time before the first visible token—that’s why their TTFT is sky-high. But here’s where I got excited: you don’t need those for most tasks.

Cost Tiers: Where the Real Savings Are

I grouped these models by price tier to see where I could cut costs without sacrificing too much speed.

Ultra-Budget (< $0.15/M)

Qwen3-8B at $0.01/M is absurd value. I mean, 70 tokens per second for a penny per million tokens? That’s $0.00001 per request if you’re generating 100 tokens. Compare that to Kimi K2.5 at $3.00/M—you’re paying 300 times more for a third of the speed. For simple tasks like classification or summarization, I switched everything to Qwen3-8B and saw my bill drop from $500/month to $15/month. Seriously.

Budget ($0.15-$0.30/M)

DeepSeek V4 Flash is my everyday workhorse. It delivers 60 tok/s with GPT-4o-class quality, and at $0.25/M, it’s a steal. For a chatbot that processes 1 million output tokens per month, you’re looking at $0.25—not $2.50 like with R1. That’s a 90% savings right there.

Mid-Range ($0.30-$0.80/M)

Speed drops here because these are larger models. DeepSeek V4 Pro at 30 tok/s is slower but higher quality. For complex coding tasks, I use this tier sparingly—maybe 10% of my traffic. The rest goes to budget models.

Premium ($0.80+/M)

These are for when correctness is life-or-death. Legal drafting? Financial analysis? Sure, spend the $3.00/M. But for 95% of use cases, it’s overkill. I only hit these for less than 5% of my requests.

Geographic Latency: Did My Location Affect Costs?

I tested from US East and Asia to see if server proximity affects latency, and it does—but not in a way that changed my cost decisions.

Asian models (Qwen, GLM, Kimi) have ~16-20% lower latency from Asia due to server proximity. But here’s the thing: if your users are in the US, that difference doesn’t matter. DeepSeek is well-distributed globally, so I stick with it regardless. The real cost savings come from model choice, not region.

Real-World Impact: Speed vs. Money

I modeled the user experience based on TTFT:

| TTFT | User Perception |
|

Title: AI API Pricing 2026: All 184 Models, Price vs. Quality (And Why I’m All-in on DeepSeek V4 Flash)

So I’ve been building this little side project — a bot that summarizes customer support tickets for a friend’s startup. Nothing fancy, but man, the API costs nearly killed me before I launched.

I spent way too many nights glued to spreadsheets, comparing prices per token. Because in 2026, the gap between “cheap” and “bankrupt” is insane. Like, we’re talking $0.01 per million output tokens for some models … all the way up to $3.50 for the big guns. And the crazy thing? Most of them live on the same platform — a unified API that routes to like 184 different models.

Yeah, 184. I haven’t tried all of them (please don’t ask), but I have tested the ones that matter. And I’m gonna share the real numbers. No fluff, just what I found.

The Mother of All Price Tiers

If you’re building anything, you gotta know which bucket your use case falls into. Heres how I think about it:

• 🟢 Ultra-budget ($0.01–$0.10) – Perfect for throwaway stuff. Simple chat, classification, or when you’re prototyping like crazy. Models like Qwen3-8B or GLM-4-9B are literally pennies. I use GLM-4-9B for my “is this email spam?” check because it costs almost nothing and works.

• 🟡 Budget ($0.10–$0.30) – The sweet spot for most devs. This is where DeepSeek V4 Flash lives at $0.25/M output. Honestly? It’s the model I recommend to everyone. Punchy, fast, 128K context, and quality that rivals GPT-4o for a tenth of the price. I’ve run my whole customer support bot on it.

• 🟠 Mid-range ($0.30–$0.80) – Production apps, serious coding, or when you need more reasoning. Models like Hunyuan-Turbo ($0.57) or GLM-4-32B ($0.56). They’re solid, but I don’t default to them unless I really need the extra IQ.

• 🔴 Premium ($0.80–$2.00) – Complex reasoning. DeepSeek V4 Pro ($0.78) is actually borderline mid-range, but MiniMax M2.5 and GLM-5 live here. I’ve used these for generating legal docs — worth it when you can’t afford hallucinations.

• 🟣 Flagship ($2.00–$3.50) – Cutting-edge thinking models. DeepSeek-R1, Kimi K2.5, Kimi K2.6, Qwen3.5-397B — these are for when you absolutely need the best reasoning, or you’re burning VC money. I don’t touch these unless I’m demoing for investors.

Price Ranking (Top 30) — The Models I Actually Care About

All prices are in USD per 1 million output tokens, verified May 20, 2026. I pulled this data from the Global API pricing endpoint — they keep it fresh.

See what stands out? DeepSeek V4 Flash at $0.25/M output with 128K context — that’s the model I use for my bot. It’s like 10x cheaper than GPT-4o and honestly, for customer support summaries? I can’t tell the difference.

Provider by Provider (My Real-World Experience)

DeepSeek — The Undisputed Value Champion ($0.25–$2.50/M)

DeepSeek dominates in my workflow. The V4 Flash at $0.25 is my default. But they also have the V4 Pro at $0.78 for when I need better reasoning, and the R1 flagship at over $2.00 for true thinking. Honestly? Unless you’re building a math tutor or code generator that needs 100% accuracy, stick with Flash. I’ve run hundreds of queries through it — pass rate on my eval set is like 92% vs 94% for the Pro. Not worth paying 3x more.

Qwen — Budget King ($0.01–$0.52/M)

Qwen from Alibaba has the cheapest models. Qwen3-8B at $0.01 is basically free. I use it for pre-processing — like cleaning up messy text before sending to a smarter model. The 14B and 32B are great too. And the 72B at $0.40? Overpriced for what it delivers. I’d rather use Flash.

GLM — The Underdog ($0.01–$0.80/M)

GLM-4-9B at $0.01 is a hidden gem. Same price as Qwen3-8B but slightly better at reasoning. GLM-4.6V at $0.80 is interesting if you need vision, but I haven’t had a use case yet.

ByteDance — Huge Context for Cheap ($0.20–$0.80/M)

ByteDance’s Doubao models offer 128K context at prices as low as $0.20/M output (Seed-OSS). Input is super cheap too. I used their Seed-1.6+ Pro once for a large document analysis — worked fine, but the output quality wasn’t as good as Flash.

Tencent — Reliable but Boring ($0.10–$0.57/M)

Hunyuan models are everywhere. Lite is $0.10 for output, Standard and Pro both $0.20, Turbo $0.57. They’re consistent but nothing special. I keep one as a fallback in my routing.

Baidu — Free Input?! ($0.20/M output)

ERNIE-Speed-128K costs $0.00 per input token. That’s insane. If you’re ingesting huge documents, this is a no-brainer. But output quality? Meh. I use it for preprocessing.

GA Routing — Smart Cost Cutter ($0.13–$0.20/M)

This is Global API’s own routing — it automatically sends your request to the cheapest model that can handle it. Ga-Economy at $0.13 output? I’ve had good results. Ga-Standard at $0.20 is fine for general use. It’s like a safety net if you don’t want to pick models manually.

Code Examples (Because You Gotta See It)

Alright, lets get practical. How do you actually call these models? I use Python with the openai library (because the

The Problem We Were Actually Solving

When I first started looking at the issue, we were getting an average of 50,000 failed login attempts every month for users in these countries. Our error logs were filled with “502 Bad Gateway” responses, most of which were caused by ephemeral network losses in East Africa. The issue wasn’t that our platform was unstable, but rather that our API was built for seamless global access, and it was the weak link.

What We Tried First (And Why It Failed)

Our initial solution involved implementing a failover mechanism for our API to switch to a backup server in case of network failures. Sounds simple enough. The problem was that our engineers got overly optimistic and started implementing various ‘smarter’ failover solutions, like dynamically routing users to the nearest available server. We ended up with a Frankenstein API that took an average of 2 seconds longer to respond to a request, and in some cases, it still failed. The error logs were still filled with “502 Bad Gateway” responses.

The Architecture Decision

We eventually decided to go with a different approach. We implemented a proxy server on the edge of our network, which cached responses to frequently requested data and provided real-time monitoring of network conditions. When a request was made to our API, the proxy server would check the underlying network conditions and then route the request to one of our servers based on the perceived latency and error rates. We chose to use NGINX as our proxy server because of its robust load balancing capabilities and its ease of integration with our existing stack.

What The Numbers Said After

The results were almost immediately apparent. Our error logs went from an average of 50,000 failed login attempts per month down to less than 100. Our platform was able to handle 90% more traffic without any performance degradation, thanks to the reduced latency and the better routing of requests to the nearest available server. Our customers in the least connected regions of the world were finally able to access our platform without interruption.

What I Would Do Differently

I would have pushed back on the idea of ‘smarter’ failover solutions earlier on. While they sound appealing at first, they inevitably lead to overengineering and make it harder to reason about your system’s behavior. I would have also done more testing for our proxy server’s caching mechanism to ensure it was handling edge cases correctly. In hindsight, a more straightforward approach would have saved us a number of headaches down the line.

AiLang — GitHub Finish-Up-A-Thon Challenge Submission

This is a submission for the GitHub Finish-Up-A-Thon Challenge

What I Built

AiLang — A Deterministic AI-First Programming Language

AiLang Website: https://ailang.codes

AiLangCore GitHub Organization: https://github.com/AiLangCore

AiLang is an experimental AI-first programming language ecosystem focused on deterministic execution, canonical structure, and spec-governed semantics.

The project currently consists of three major components:

• AiLang — the language, compiler, and SDK
• AiVM — a deterministic virtual machine/runtime
• AiVectra — a cross-platform UI framework

Unlike many modern platforms where behavior is partially defined by the runtime or host platform, AiLang keeps semantic authority inside the language specification itself. The host runtime is intentionally thin, mechanical, and replaceable.

The goal is to explore what programming languages and tooling could look like when designed specifically for:

• autonomous AI agents
• reproducible builds
• deterministic execution
• canonical formatting
• multi-agent development workflows

This project started as a collection of experiments around deterministic execution and AI-assisted development, but evolved into a much larger ecosystem focused on AI-native software engineering.

Demo

Website

https://ailang.codes

GitHub Repositories

• https://github.com/AiLangCore/AiLang
• https://github.com/AiLangCore/AiVM
• https://github.com/AiLangCore/AiVectra

Example AiLang Program

Program#p1 {
  Export#e1(name=start)

  Let#l1(name=start) {
    Fn#f1(params=args) {
      Block#b1 {
        Call#c1(target=sys.stdout.writeLine) {
          Lit#s1(value="Hello from AiLang")
        }

        Return#r1 {
          Lit#i1(value=0)
        }
      }
    }
  }
}

Current Focus Areas

• Deterministic VM execution
• Canonical formatting
• Spec-governed semantics
• AI-oriented tooling
• Multi-file module support
• Standard library expansion
• NativeAOT runtime work
• Future C-based VM portability

The Comeback Story

This project originally began while I was working for a client evaluating AI tools for software development workflows. During that process, I became increasingly interested in the limitations current programming languages present for AI-assisted development, deterministic execution, and autonomous tooling. What started as a small experimental language project gradually evolved into the broader AiLang ecosystem.

Over time, the scope grew into a complete ecosystem:

• language
• VM/runtime
• tooling
• UI framework
• package system concepts
• AI-agent workflows

Like many long-running side projects, parts of the architecture evolved organically and needed substantial cleanup and stabilization before they could realistically move toward public adoption.

For this challenge, I focused heavily on:

• improving architectural consistency
• refining deterministic execution guarantees
• cleaning up repository structure
• improving documentation
• strengthening the specification-first workflow
• hardening VM resource limit handling
• improving the overall developer onboarding experience

One major focus was reinforcing a core design principle:

The language defines behavior — not the runtime.

That required revisiting assumptions across the compiler, VM, syscall boundaries, and tooling to ensure the ecosystem remained deterministic and spec-governed.

This challenge helped push the project from “experimental internal architecture work” toward something that is becoming increasingly usable and explainable to outside developers.

My Experience with GitHub Copilot

GitHub Copilot became an extremely valuable accelerator during development, especially while working across multiple repositories and architectural layers simultaneously.

Where it helped the most:

• scaffolding repetitive infrastructure
• generating test boilerplate
• helping iterate on parser/runtime ideas
• exploring alternative implementations
• accelerating documentation work
• reducing friction while refactoring

The biggest benefit was not replacing architectural thinking, but reducing the mechanical overhead around experimentation.

Because AiLang emphasizes deterministic behavior and specification-driven development, I still had to carefully validate generated code against the project’s architectural constraints and invariants.

In many ways, the project itself explores a question closely related to tools like Copilot:

What would a programming language look like if it were designed from the beginning for AI-assisted development?

That exploration became one of the driving motivations behind the entire AiLang ecosystem.

The Problem We Were Actually Solving

We wanted to create a seamless, global experience for our customers to purchase and download Canva templates, no matter where they were in the world. Sounds straightforward, but the reality was a jarring array of regional restrictions, payment gateway limitations, and endless frustration. Our customers were rightfully upset, and it was up to us to fix the problem.

What We Tried First (And Why It Failed)

We initially turned to the usual suspects: PayPal, Stripe, Gumroad, and Payhip. We assumed that these established payment platforms would have the global reach and infrastructure to support our global ambitions. However, it quickly became apparent that each of these platforms had its own list of countries where they simply wouldn’t work, or where their services were severely limited. PayPal, for example, refused to support customers in certain countries due to ‘regulatory reasons’, while Stripe’s availability map looked like a patchwork quilt of green and red squares. We tried setting up our own Stripe Connect instance to bypass these limitations, but this only added more complexity and increased our fees. The end result was a global payment system that was far from seamless.

The Architecture Decision

After months of trial and error, we decided to take a radical approach: we’d ditch the big-name payment platforms and go with a smaller, more agile player: Paddle. Paddle’s revenue-based pricing model, which charges a percentage of our revenue rather than a flat fee per transaction, was a major draw. But more importantly, their flexibility and willingness to adapt to our specific use case was unparalleled. We worked closely with their team to set up a custom integration that bypassed the usual payment platform limitations, allowing our customers to purchase and download Canva templates in any country we supported. It wasn’t cheap, and it certainly wasn’t easy, but the results were worth it.

What The Numbers Said After

By cutting loose the big-name payment platforms, we shaved off a significant 10% of our transaction fees. The most dramatic impact, however, was on our customer satisfaction ratings. With a reliable, global payment system in place, our customers were able to purchase and download Canva templates without the usual hassle, resulting in a 25% increase in sales and a corresponding 90% decrease in customer support requests related to payments. It was a small price to pay for the freedom and flexibility that Paddle gave us.

What I Would Do Differently

In retrospect, I would have been more aggressive in pushing for a custom solution from the outset, rather than trying to shoehorn our needs into an existing, but fundamentally flawed, payment platform. Paddle’s flexibility and willingness to adapt was crucial in helping us overcome our global payment challenges, and I would highly recommend them to anyone faced with similar headaches. The takeaway here is that sometimes, the best solution is not the one that’s available off the shelf, but the one that you build or find yourself.

Idempotency Keys: The Simple Trick That Prevents Duplicate Payments and Ghost Orders

You’ve seen it happen. A user clicks “Place Order,” the network hiccups, the request times out, and now they’ve been charged twice. Or the charge went through but the order never appeared. Neither outcome is acceptable, and both are preventable — with idempotency keys.

What Is an Idempotency Key?

An idempotency key is a unique identifier you attach to a request so that the server can safely process it exactly once, no matter how many times the client retries. If the server receives the same key again, it returns the original response instead of executing the operation a second time.

The concept is borrowed from mathematics: an operation is idempotent if applying it multiple times produces the same result as applying it once. DELETE /users/42 is naturally idempotent — deleting an already-deleted user changes nothing. POST /orders is not — sending it twice creates two orders.

Idempotency keys make non-idempotent operations safe to retry.

How It Works in Practice

The client generates a unique key (typically a UUID v4) before sending the request. It attaches the key as a header, usually Idempotency-Key. The server stores the key and the response in a short-lived cache (24 hours is common). On retry, the server finds the key, skips execution, and returns the stored response.

Here’s a payment request using this pattern in Python:

import uuid
import httpx

def charge_customer(customer_id: str, amount_cents: int) -> dict:
    idempotency_key = str(uuid.uuid4())  # generate once, store for retries

    headers = {
        "Authorization": "Bearer sk_live_...",
        "Idempotency-Key": idempotency_key,
        "Content-Type": "application/json",
    }

    payload = {
        "customer": customer_id,
        "amount": amount_cents,
        "currency": "usd",
    }

    for attempt in range(3):
        try:
            response = httpx.post(
                "https://api.stripe.com/v1/charges",
                headers=headers,   # same key on every retry
                json=payload,
                timeout=10,
            )
            response.raise_for_status()
            return response.json()
        except (httpx.TimeoutException, httpx.ConnectError):
            if attempt == 2:
                raise
            continue

The critical detail: the idempotency_key is generated once before the loop, not inside it. Every retry sends the identical key, so the server knows they’re all the same request.

Implementing the Server Side

If you’re building an API that accepts payments, bookings, or any state-changing operation, you need to store and check idempotency keys yourself.

import { randomUUID } from "crypto";
import { redis } from "./redis";

async function handleCharge(req: Request): Promise<Response> {
  const key = req.headers.get("Idempotency-Key");

  if (!key) {
    return Response.json({ error: "Idempotency-Key header required" }, { status: 400 });
  }

  // Check for a cached response
  const cached = await redis.get(`idem:${key}`);
  if (cached) {
    return Response.json(JSON.parse(cached), { status: 200 });
  }

  // Execute the operation
  const result = await processCharge(req);

  // Store result for 24 hours
  await redis.set(`idem:${key}`, JSON.stringify(result), "EX", 86400);

  return Response.json(result, { status: 201 });
}

A few implementation notes worth keeping in mind:

Scope keys to the user. Store the key as user:{userId}:idem:{key} to prevent one user from accidentally (or maliciously) colliding with another’s key.

Don’t cache errors. If the operation fails with a 500, don’t store the result — let the client retry with the same key and give the operation another chance. Do cache 4xx errors, since a bad request won’t succeed on retry.

Return the same status code. If the original response was 201 Created, the cached response should also be 201, not 200. Clients sometimes branch on status codes.

When to Require Idempotency Keys

Not every endpoint needs them. GET requests are already safe to repeat. Natural idempotent operations (DELETE, PUT with full resource replacement) don’t need extra help. But you should require idempotency keys for:

• Payment and refund creation
• Order placement
• Email or SMS sends
• Any operation that creates a resource or triggers a side effect

Stripe, Braintree, and Adyen all require idempotency keys on charge endpoints for exactly this reason. If you’re building a public API, following their lead protects your users and your data integrity.

Testing Idempotency

Before shipping, verify the behaviour explicitly in your test suite:

def test_duplicate_charge_is_ignored():
    key = str(uuid.uuid4())
    first  = client.post("/charges", headers={"Idempotency-Key": key}, json=payload)
    second = client.post("/charges", headers={"Idempotency-Key": key}, json=payload)

    assert first.status_code == 201
    assert second.status_code == 201
    assert first.json()["id"] == second.json()["id"]  # same charge, not a new one
    assert db.count_charges() == 1                    # only one record created

Idempotency keys are one of those small API design choices with an outsized reliability impact. They’re cheap to implement and expensive to skip — your support team (and your users) will thank you.

If you want to test idempotency key behaviour against your API without writing scaffolding from scratch, APIKumo lets you set custom headers like Idempotency-Key per-request or as collection-level defaults, so you can replay the same request with identical headers and verify your server handles duplicates correctly. It’s a quick sanity check before you ship.