Idempotency

Idempotency keys ensure that retrying the same write does not create duplicate work.

Where it matters most

• conduitClient.reports.create(...)
• conduitClient.primitives.media.upload(...)
• conduitClient.primitives.jobs.cancel(...)

Key rule

Reuse the same idempotency key only for the same logical operation and the same request shape.

Report creation example

import { Conduit } from "@mappa-ai/conduit"

const conduitClient = new Conduit({ apiKey: process.env.CONDUIT_API_KEY! })

const receipt = await conduitClient.reports.create({
  source: { mediaId: "media_abc123" },
  output: { template: "general_report" },
  target: { strategy: "dominant" },
  idempotencyKey: "report_20260117_user456_v1",
  webhook: { url: "https://your-app.com/webhooks/conduit" },
})

console.info(receipt.jobId)

Media upload example

import { createHash } from "crypto"
import { readFile } from "fs/promises"

async function uploadWithRetry(path: string) {
  const bytes = await readFile(path)
  const hash = createHash("sha256").update(bytes).digest("hex")

  return conduitClient.primitives.media.upload({
    path,
    idempotencyKey: `upload_${hash.slice(0, 16)}`,
  })
}

Retry guidance

• retry transient failures like 429, transient 5xx, and transient network errors
• do not retry auth or validation failures with the same request unchanged
• keep the same idempotency key across intentional retries
• switch to a new key only when you intentionally submit a materially new attempt

Retention window

Cached idempotent responses are retained for 24 hours.