Waafir
Esta página es una traducción automática pendiente de revisión humana. Puede contener errores.

Reintentar de forma segura con una clave de idempotencia

Esta receta muestra cómo reintentar de forma segura la llamada de inicio de importación tras un fallo de red o un error ambiguo. La cabecera Idempotency-Key en POST /api/v1/monitoring/loan/imports hace que la segunda llamada devuelva el mismo ID de importación que la primera, con una URL de carga recién generada: no se crea ninguna importación duplicada.

Cuándo usarlo

Siempre que no pueda saber si la llamada anterior de inicio de importación llegó a registrarse. Los dos casos canónicos:

  • Su cliente HTTP generó un tiempo de espera agotado antes de que llegara la respuesta. Es posible que la solicitud llegara a Waafir e iniciara una importación; usted no lo sabe.
  • Recibió un error 5xx de una superficie no idempotente y quiere reintentar sin arriesgarse a duplicar trabajo.

La convención de toda la plataforma es que todos los endpoints que modifican datos aceptan Idempotency-Key: el endpoint de inicio de importación aquí, el endpoint de exportación y los endpoints de modificación de auditoría en otros lugares. Use una clave nueva por cada operación lógica; reutilícela en los reintentos de la misma operación. Un patrón habitual es un UUID v4 generado una vez por cada intención de «lote de importación diaria» y conservado en el estado de su trabajo hasta que la llamada se complete correctamente.

El contrato

  • La cabecera es Idempotency-Key: <your-string>. Máximo 255 caracteres.
  • El cuerpo también acepta un campo idempotencyKey; la cabecera tiene prioridad cuando ambos están presentes. Prefiera la cabecera: es la ubicación canónica en toda la plataforma.
  • Una llamada repetida con el mismo (orgId, idempotencyKey) devuelve:
    • el mismo importId,
    • reused: true en la respuesta,
    • una URL de carga recién generada (la URL original caduca; la nueva es la que se debe usar).
  • Una llamada repetida con un cuerpo diferente pero la misma clave se rechaza; la clave queda vinculada a la forma de la solicitud original.

La receta

# curl — start an import with an idempotency key, then retry safely
set -euo pipefail

PAT="${WAAFIR_PAT}"
BASE_URL="${WAAFIR_BASE_URL:-https://app.waafir.io}"
NDJSON_FILE="loans-2026-05-22.ndjson"
# Generate a fresh key per logical batch intent; keep it stable across retries.
IDEMPOTENCY_KEY="loan-import-2026-05-22-$(uuidgen)"

start_import() {
  curl -fsS -X POST "${BASE_URL}/api/v1/monitoring/loan/imports" \
    -H "Authorization: Bearer ${PAT}" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
    -d "$(cat <<JSON
{
  "kind": "loan",
  "filename": "${NDJSON_FILE}",
  "sizeBytes": $(stat -c%s "${NDJSON_FILE}")
}
JSON
)"
}

# First call. If the network bombs out we have no idea whether the
# request landed — but the same key on the next attempt guarantees no
# duplicate import.
RESULT=$(start_import || true)

if [ -z "${RESULT}" ] || ! echo "${RESULT}" | jq -e .importId > /dev/null; then
  echo "first call ambiguous; retrying with the same idempotency key…"
  RESULT=$(start_import)
fi

echo "${RESULT}" | jq '{importId, reused, uploadUrl}'
# On a retry, reused == true; the importId matches the first call's; the
# uploadUrl is fresh.
// TypeScript — retry start-import safely with an Idempotency-Key
import { randomUUID } from "node:crypto";
import { statSync } from "node:fs";

const PAT = process.env.WAAFIR_PAT!;
const BASE_URL = process.env.WAAFIR_BASE_URL ?? "https://app.waafir.io";
const NDJSON_FILE = "loans-2026-05-22.ndjson";
const idempotencyKey = `loan-import-2026-05-22-${randomUUID()}`;

async function startImport() {
    return fetch(`${BASE_URL}/api/v1/monitoring/loan/imports`, {
        method: "POST",
        headers: {
            Authorization: `Bearer ${PAT}`,
            "Content-Type": "application/json",
            "Idempotency-Key": idempotencyKey,
        },
        body: JSON.stringify({
            kind: "loan",
            filename: NDJSON_FILE,
            sizeBytes: statSync(NDJSON_FILE).size,
        }),
    });
}

// Retry up to 3 times on transient failures; the same key makes this safe.
let lastError: unknown;
let result: { importId: string; reused: boolean; uploadUrl: string } | null = null;
for (let attempt = 1; attempt <= 3; attempt++) {
    try {
        const res = await startImport();
        if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
        result = (await res.json()) as typeof result;
        break;
    } catch (err) {
        lastError = err;
        console.warn(`attempt ${attempt} failed; retrying with same idempotency key`, err);
        await new Promise((r) => setTimeout(r, 1_000 * attempt));
    }
}

if (!result) throw lastError;
console.log({ importId: result.importId, reused: result.reused, uploadUrl: result.uploadUrl });
# python — retry start-import safely with an Idempotency-Key
import os
import uuid
import time
import requests
from pathlib import Path

PAT = os.environ["WAAFIR_PAT"]
BASE_URL = os.environ.get("WAAFIR_BASE_URL", "https://app.waafir.io")
NDJSON_FILE = Path("loans-2026-05-22.ndjson")

idempotency_key = f"loan-import-2026-05-22-{uuid.uuid4()}"

def start_import():
    return requests.post(
        f"{BASE_URL}/api/v1/monitoring/loan/imports",
        headers={
            "Authorization": f"Bearer {PAT}",
            "Content-Type": "application/json",
            "Idempotency-Key": idempotency_key,
        },
        json={
            "kind": "loan",
            "filename": NDJSON_FILE.name,
            "sizeBytes": NDJSON_FILE.stat().st_size,
        },
        timeout=30,
    )

# Retry up to 3 times on transient errors. The same key makes a second
# successful call a guaranteed replay of the first.
last_exc = None
result = None
for attempt in range(1, 4):
    try:
        response = start_import()
        response.raise_for_status()
        result = response.json()
        break
    except requests.RequestException as exc:
        last_exc = exc
        print(f"attempt {attempt} failed; retrying with same idempotency key: {exc}")
        time.sleep(attempt)

if result is None:
    raise RuntimeError("all retries exhausted") from last_exc

print({
    "importId": result["importId"],
    "reused": result["reused"],
    "uploadUrl": result["uploadUrl"],
})

Qué verificar

En una primera llamada correcta, reused es false. En cualquier llamada posterior con la misma clave, reused es true e importId es igual al de la primera llamada. La uploadUrl se regenera en cada llamada, por lo que reintentar después de que caduque una URL obsoleta es seguro: use siempre la URL de la respuesta más reciente.

Si reintenta con un cuerpo de solicitud diferente y la misma clave, la API devuelve un error que indica que la clave está vinculada a una forma de solicitud en conflicto; rote la clave para la nueva intención.