Idempotency and retries

An idempotency key identifies one logical model operation. Reuse it when retrying the same operation, and use a new key for a new operation. Enlitt recognizes keys for at least 30 days after the call that claimed them. Within that window, a repeated key does not begin a second billed operation. Afterward, do not depend on whether a key is still recognized.

Vercel adapter

import { enlitt, ENLITT_STANDARD_MODEL } from "@enlitt/sdk/vercel";
import { generateText } from "ai";

const idempotencyKey = "ticket-42-summary-attempt";
const result = await generateText({
  model: enlitt(ENLITT_STANDARD_MODEL),
  prompt: "Summarize ticket 42.",
  providerOptions: { enlitt: { idempotencyKey } }
});

The supplied key is a base of 16–200 visible ASCII characters. The Vercel adapter appends the number of prompt items to distinguish underlying model invocations in a tool loop. Retrying a step with the same base and prompt item count derives the same identity. Each new step is billed as its own call.

The suffix is a count, not a content hash. Do not reuse the base for a different prompt just because it has the same number of items. If you omit a key, the adapter creates a fresh base for each invocation; your application's separate attempts then have different identities.

OpenAI and core calls

Pass enlitt: { idempotencyKey } in an OpenAI responses.create() body. For withPremiumCharge(), pass idempotencyKey in its options. These use the key directly because each invocation represents one model operation.

Deduplication does not promise output replay

A repeated call can return operation_in_progress, a conflict, or idempotency_replay_unavailable. Premium content stays in your application and provider, so Enlitt cannot replay it. Persist results in your own system when you need to recover output after a network interruption.

Generate or save the key before your retry loop. Generating a fresh key inside every attempt defeats deduplication. Avoid concurrent calls with the same key, and never change a call's pricing or inputs under an already-used identity.