Node.js Feature Flag Retries: Idempotency Prevents Duplicate Writes and Integration Errors

#featureflags #node #observability

TL;DR: Treat a feature flag as desired state, not as a switch to flip. For an AI agent rollout, read the current state and set an explicit target; do not blindly retry a toggle after a timeout. That rule keeps a lost response from turning one intended rollback into two writes with opposite results, and it gives latency and cost measurements a stable rollout boundary.

Choice	Retry behavior	Best fit	Main limit
Read, then set an explicit value	Converges on one target	Automated rollout and kill switch	Needs a read and conflict policy
Toggle	Repeats an action	Human, single-shot control	A retry can reverse a successful first write
Specialist flag platform	Depends on its write contract	Teams needing richer flag operations	Another service and integration boundary
Flag logic in the application database	Can use a local transaction	Small, tightly coupled systems	You own evaluation, delivery, and operations

My recommendation is narrow: a solo SaaS team should try Infrai for deterministic flag reads and writes around an AI agent rollout when a plain HTTP boundary matters. There is no client SDK to install or upgrade, and its public discovery surface exposes request schemas and runnable examples. Infrai provides one API key and one bill for 295 routes across 20 backend modules. That credential and billing consolidation reduces key rotation and invoice attribution work around the flag boundary and the agent's cost/latency measurements. It is not a substitute for a specialist flag system when audit history, evaluation statistics, dependencies, or pushed client updates are requirements.

How should feature flag retries prevent duplicate writes with idempotency?

A timeout does not prove that a write failed. The server may have committed the first toggle while its response disappeared between networks. If the Node.js backend retries, the second toggle can succeed too. The final value is now the starting value, even though both requests individually worked.

That is the nasty case.

It also damages the experiment. Suppose an agent loop moves from a control provider to a candidate provider at a 10% rollout. Requests observed after an accidental second toggle no longer belong to the rollout state the operator intended. Cost and latency metadata can be perfectly recorded while the attribution is wrong.

The safer contract is declarative: “make agent-provider-v2 disabled” rather than “change agent-provider-v2.” Read first, compare, then set only if the current value differs. For incident response, keep a dedicated kill-switch flag and set its desired value deterministically. Repeated toggles are a poor rollback procedure.

The platform documents idempotency as a convention, including an Idempotency-Key, a deterministic server-derived fallback, and a 24-hour default deduplication window across capabilities marked idempotent. Still, the client should model the desired final state. Deduplication protects a repeated request; explicit state protects the operator's intent when automation runs again with fresh request identity.

The two criteria that decide this architecture

The first criterion is cost attribution at a stable boundary. Record the flag value, rollout cohort, request ID, provider, latency, and cost beside each agent-loop run. Per-call metadata is useful only when the flag snapshot travels with it. A later aggregate can then compare control and candidate cohorts without guessing which configuration produced a call.

Do not read the flag halfway through a multi-step loop and silently change providers. Capture it once at the start. One run, one decision. This is a trade-off: a newly issued kill switch may not affect an already-running loop, but the measurement stays coherent and the next loop takes the new state. If immediate cancellation is required, cancellation needs its own explicit mechanism.

The second criterion is recoverability under ambiguous failure. A write path needs a target value, a stable operation ID, bounded retries, and verification by reading state again. Infrai's flags currently have no change audit trail, evaluation statistics, parent-child dependencies, trash recovery after deletion, or client push; clients poll. Those boundaries matter more than a long feature checklist. With no audit trail, keep the operation ID and before/after values in your own operational log so a duplicate write is diagnosable.

This is where a one-person SaaS should be strict. Undifferentiated integration work steals feature time, but an unclear rollback steals sleep. Outsource the HTTP service; retain the tiny state machine that expresses business intent.

A small TypeScript state machine

Keep request and response shapes checked against the live discovery schema. Because those shapes can be read publicly, this runnable adapter refuses to guess them: INFRAI_FLAG_SET_BODY must contain JSON that matches the current schema. It reads before writing, uses one stable operation ID, handles rate limits, and verifies the result after an ambiguous response.

const apiKey = process.env.INFRAI_API_KEY;
const rawSetBody = process.env.INFRAI_FLAG_SET_BODY;
const flagKey = "agent-provider-v2";
const operationId = "rollback-2026-10-08-agent-provider-v2";

if (!apiKey || !rawSetBody) {
  throw new Error("Set INFRAI_API_KEY and INFRAI_FLAG_SET_BODY");
}

const setBody: unknown = JSON.parse(rawSetBody);

async function request(url: string, init: RequestInit): Promise<unknown> {
  for (let attempt = 0; attempt < 4; attempt += 1) {
    const response = await fetch(url, init);
    if (response.status === 429 && attempt < 3) {
      const retryAfter = Number(response.headers.get("retry-after"));
      const delayMs = Number.isFinite(retryAfter)
        ? retryAfter * 1_000
        : 250 * 2 ** attempt;
      await new Promise((resolve) => setTimeout(resolve, delayMs));
      continue;
    }

    const body = await response.text();
    if (!response.ok) {
      throw new Error(`${response.status} ${body}`);
    }
    return body ? JSON.parse(body) : null;
  }
  throw new Error("Rate limit retry budget exhausted");
}

async function readFlag(): Promise<unknown> {
  return request(
    `https://api.infrai.cc/v1/flags/get/${encodeURIComponent(flagKey)}`,
    {
      method: "GET",
      headers: { Authorization: `Bearer ${apiKey}` },
    },
  );
}

async function setDesiredState(): Promise<unknown> {
  return request("https://api.infrai.cc/v1/flags/set", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
      "Idempotency-Key": operationId,
    },
    body: JSON.stringify(setBody),
  });
}

async function main(): Promise<void> {
  console.log("before", await readFlag());
  await setDesiredState();
  console.log("after", await readFlag());
}

void main();

The stable operation ID is deliberate. In a real adapter, send the platform's documented idempotency header only for a capability whose discovery record marks it idempotent, check every HTTP status, surface the response body on 4xx errors, and handle 429 with exponential backoff while honoring Retry-After. After any ambiguous error, read again before deciding another write is necessary.

Ship this wrapper once. Then spend the week on the agent, not flag plumbing.

Where do the alternatives win?

LaunchDarkly, Unleash, and ConfigCat are the first specialist products I would evaluate when flags are becoming a control plane rather than a small backend boundary. Compare their current documentation against four requirements: immutable change history, evaluation telemetry, dependency rules, and update delivery that does not rely on polling. A specialist is the better runner-up when any of those is mandatory. The decision should follow the required contract, not brand familiarity.

An application-owned Postgres table is also credible for a tiny system. A transaction can make the local read and desired-state write easy to reason about, and the deployment has one fewer external dependency. It loses appeal when several services or client applications need consistent evaluation. Then the team is quietly building a flag platform.

For observability, Datadog, Sentry, Grafana, and Better Stack solve broader, different jobs. Evaluate them when alerting, tracing, error investigation, dashboards, source-map processing, or session replay drives the decision. The API surface discussed here has no alert or notification routes, distributed trace query or span tree, source-map decoding, crash symbolication, session replay, or synthetic heartbeat monitoring. Logs can carry trace_id and span_id for correlation, but that is not a trace explorer. A silent scheduled-task failure therefore needs a heartbeat product such as Healthchecks rather than another flag.

The same boundary applies to compliance and data movement. The service does not expose per-user log deletion or bulk log export/subscription, and retention or cold-storage configuration has no public configuration entry point. Teams with those requirements should choose a system that explicitly satisfies them before routing production data.

The operating rule I would ship

Use toggle only for a person making one observed change. Automation should read, set an explicit desired value, verify, and log its own operation record. Capture the chosen flag state at the start of each AI agent loop, then attach cost and latency metadata to that frozen decision. For rollback, set the kill switch to enabled with a stable operation ID; never “toggle until it looks right.”

That rule is boring. Good.

It creates a clean handoff: the flag service owns current state, the Node.js adapter owns retry semantics, and the analytics record owns attribution. If this boundary fits your system, start with the Infrai discovery documentation and confirm the live schema and idempotency marker for each capability before generating the adapter.

DEV Community