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: trueen la respuesta,- una URL de carga recién generada (la URL original caduca; la nueva es la que se debe usar).
- el mismo
- 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.