The Idempotency Layer AI Coding Tools Keep Skipping

A job post that reads like a bug report

There's a remote PHP listing making the rounds, senior backend, 15-25k, and if you skim the requirements it looks like a wishlist. Read it again and it's really a confession about how teams ship now.

Requirement eight asks for transactions, idempotency, concurrency control, cache consistency, slow-SQL cleanup, and rate-limit compensation. Requirement twelve asks the candidate to use AI coding tools fluently but to independently judge business logic and security risk. The job description itself repeats it: own transaction idempotency, scheduled jobs, exception compensation, and data reconciliation, and manually review anything the AI generates.

Put those two lines next to each other and the shape of the problem is obvious. The model writes the endpoint. A person is expected to own what happens when that endpoint gets called twice. Nobody spells out why, but the split is right there in the hiring criteria: fast generation on one side, retry safety and reconciliation on the other, explicitly kept as a human responsibility.

That's the signal worth building around. Not "AI can't code" and not "AI writes everything now." The interesting part is where the line falls. Tools like the ones this candidate is expected to run, the same AI coding assistants showing up across the other job posts in the wild right now, are very good at producing a handler that works on the first, clean request. They are much less reliable about the second, duplicate request that arrives because a phone lost signal, a load balancer retried, or a user tapped Pay twice.

Why the happy path is the trap

A payment or order handler that only considers the happy path is the classic double-charge waiting to happen. Client sends the request, the network drops the response, the client retries, and now the same charge runs twice. The model's code was not wrong on its own terms. It just answered the question it was asked, which was "process this request," not "process this request at most once even if it shows up five times."

Idempotency is the standard answer, and it's an old idea: the caller attaches a unique key to a request, the server remembers the first result for that key, and any later request carrying the same key gets the stored result back instead of running the operation again. Stripe-style APIs have done this for years. The PHP post is asking for exactly this discipline by name.

The reusable move here isn't rewriting the handler the model already generated quickly. It's putting a small, inspectable idempotency-key store in front of it. Capture the key on the way in. If it's new, let the request through and record what it resolved to. If it's seen, replay the stored response and don't touch the downstream operation at all. Keep a ledger you can actually read when someone asks why a key returned what it did.

That boundary is small enough to own by hand, which is the whole point. It's the part a human keeps after the AI ships the rest.

Building the store on VicroCode

Here's how I'd stand this up with the platform's confirmed pieces, keeping it deliberately boring.

The key-store is a hosted API endpoint. You can run Python online for the logic and expose it as an endpoint that your existing handlers call before they do any real work. The flow is short:

1. Read the idempotency key from the incoming request (a header the caller sets, or a hash of the meaningful request fields).
2. Look the key up in storage.
3. If it's missing, insert a row marking the key as in-progress, let the caller proceed, then record the final response body and status against that key.
4. If it's present and complete, return the stored response verbatim.
5. If it's present but still in-progress, return a "still processing" signal so a fast retry doesn't slip past the check.

Storage is a SQLite database, which fits this job well because the access pattern is a keyed lookup and a keyed write. A single table does most of the work: the key as the primary key, a status column, the stored response payload, a request fingerprint so you can detect a key being reused for a genuinely different request, and timestamps. That request fingerprint matters. Without it, a client that reuses a key for two different operations gets a silently wrong replay, which is worse than a double-charge because it's harder to spot.

The ledger is the part I care about most, and it comes almost for free. Because every key and its resolution live in one table, you get an audit trail of what each key resolved to, when, and against which request shape. When something looks off in production, you open the SQLite editor, filter by key or time window, and read exactly what the layer decided. That's the inspectability the boundary is supposed to buy you. It's also the raw material for the reconciliation and data-accounting work the same job post lists as a human responsibility.

A rough sketch of the core check:

def resolve(key: str, fingerprint: str, run_operation):
    row = db.get(key)
    if row is None:
        db.insert(key, fingerprint, status="in_progress")
        result = run_operation()
        db.update(key, status="done", response=result)
        return result
    if row.fingerprint != fingerprint:
        raise KeyReusedForDifferentRequest(key)
    if row.status == "in_progress":
        return still_processing_response()
    return row.response

That's the shape, not a drop-in. Concurrency is the sharp edge: two requests with the same new key arriving at nearly the same instant can both see "missing" unless the insert is the thing that enforces uniqueness. Lean on the primary-key constraint so the second insert fails and that caller falls into the replay path rather than running the operation a second time. Test this specifically with overlapping requests, because it's the case that looks fine in a demo and breaks under real retries.

What this does and doesn't cover

Be honest with yourself about the boundary. This layer makes a retried request safe. It does not make a distributed transaction atomic, and it does not reconcile state that already diverged before you added it. If the downstream operation half-completes, records the response, and the response itself was wrong, the store faithfully replays the wrong answer. Idempotency is about not repeating work, not about the work being correct in the first place.

A few limits worth stating plainly. Any store that fronts payment or order flows sits in front of money, so treat authentication on the endpoint as non-negotiable, not a later task. An idempotency endpoint with no access control is an open door to your ledger and, worse, to influencing what gets replayed. Keys should carry no meaning a client could guess or forge into a collision. And the response you store should be scoped to what's safe to replay; caching a one-time token or a freshly minted secret and handing it back on every retry is its own bug.

Migrating an existing system also needs care rather than a big-bang switch. Adding a uniqueness-enforcing layer in front of a live handler changes behavior under load, and that's the kind of change worth rolling out behind a flag and watching, not shipping on a Friday. I haven't benchmarked this pattern on the platform, so treat any latency or throughput expectations as unverified until you measure your own.

The part worth keeping

Strip the evidence down and it says something simple. The market is hiring people who can use AI to move fast and still personally own the retry-safe, security-sensitive boundary. That boundary is small, specific, and reusable across every project that takes money or mutates state.

So let the assistant write the handler. Then put a key-store in front of it that captures the key, replays the stored response, and keeps a ledger you can read. Ship it once as a hosted endpoint and reuse it. The handler is cheap now. The judgment about what happens on the second call is the thing that's still worth doing yourself.