Idempotency

curl -X POST https://api.clevis.dev/v1/payouts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: payroll-co-2026-05-emp-001" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "4600000.00",
    "currency": "COP",
    "country": "CO",
    "external_id": "payroll-co-2026-05-emp-001",
    "beneficiary": { ... }
  }'

import httpx

idempotency_key = f"payroll-{country}-{year}-{month:02d}-{employee_id}"

resp = httpx.post(
    "https://api.clevis.dev/v1/payouts",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Idempotency-Key": idempotency_key,
    },
    json={
        "amount": net_salary,
        "currency": "COP",
        "country": "CO",
        "external_id": idempotency_key,   # also works as the key
        "beneficiary": { ... },
    },
)

if resp.status_code == 200:
    print("Replay — payout already existed")
elif resp.status_code == 201:
    print("Created — first time we saw this key")
elif resp.status_code == 409:
    error = resp.json()["error"]
    if error["code"] == "IDEMPOTENCY_KEY_REUSED":
        raise RuntimeError("Same key, different body — bug in caller")
    if error["code"] == "EXTERNAL_ID_CONFLICT":
        raise RuntimeError("external_id already used for a different payout")

const idempotencyKey = `payroll-${country}-${year}-${month}-${employeeId}`;

const resp = await fetch("https://api.clevis.dev/v1/payouts", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Idempotency-Key": idempotencyKey,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: netSalary,
    currency: "COP",
    country: "CO",
    external_id: idempotencyKey,
    beneficiary: { /* ... */ },
  }),
});

switch (resp.status) {
  case 201:
    console.log("Created");
    break;
  case 200:
    console.log("Idempotent replay");
    break;
  case 409: {
    const { error } = await resp.json();
    if (error.code === "IDEMPOTENCY_KEY_REUSED") {
      throw new Error("Same key with a different body");
    }
    if (error.code === "EXTERNAL_ID_CONFLICT") {
      throw new Error("external_id already used");
    }
  }
}