Inspeccionar los errores de fallo parcial tras una importación
Esta receta muestra cómo inspeccionar los errores por fila de una importación asíncrona una vez que el worker termina. El endpoint de estado muestra una breve muestra en cada lectura; el modo de errores paginados del mismo endpoint transmite todos los errores con el número de fila, el código de error, el mensaje de error y la carga de la fila sin procesar.
Cuando llega el estado partial / failed
Una sola fila incorrecta nunca aborta una importación: el worker de Waafir valida cada fila de forma independiente, guarda todas las válidas y escribe un registro de error por fila para cada una incorrecta. A continuación, la importación termina en uno de dos estados finales:
partial: al menos una fila se completó correctamente y al menos una falló. Las filas válidas se registraron; las no válidas se pueden consultar con esta receta.failed: ninguna fila se completó correctamente. O bien todas las filas eran no válidas, o bien la importación sufrió un error fatal (NDJSON mal formado, un fallo de lectura del archivo, una excepción del worker); en ese caso,errorSummarycontiene un error con forma de error fatal.
Para ambos estados finales, la receta siguiente es la herramienta adecuada para profundizar.
La estructura de la información de errores
El endpoint de estado (GET /api/v1/monitoring/loan/imports/{id}) devuelve un campo errorSummary con dos formas según lo ocurrido:
- Errores por fila (el caso habitual en ejecuciones
partialy en la mayoría de lasfailed):errorSummaryes{ samples, totals }. El arraysamplescontiene los diez primeros errores como{ rowNumber, errorCode, errorMessage, rawRow }. El campototalsmuestra un recuento agregado. - Errores fatales (una importación que se detuvo antes de procesar ninguna fila):
errorSummaryes{ fatal }: un único error que describe el fallo a nivel del worker.
Para ver más allá de los diez primeros errores, recorra el modo de errores paginados: GET /api/v1/monitoring/loan/imports/{id}?errors=true&limit=&offset=.
La receta
# curl — inspect a partial / failed import's errors
set -euo pipefail
PAT="${WAAFIR_PAT}"
BASE_URL="${WAAFIR_BASE_URL:-https://app.waafir.io}"
IMPORT_ID="${1:?supply the import id}"
# Step 1 — fetch the terminal status, see the error summary.
STATUS=$(curl -fsS "${BASE_URL}/api/v1/monitoring/loan/imports/${IMPORT_ID}" \
-H "Authorization: Bearer ${PAT}")
echo "status:" && echo "$STATUS" | jq '{status, rowCountProcessed, rowCountSucceeded, rowCountFailed}'
echo "first ten errors (sampled):"
echo "$STATUS" | jq '.errorSummary'
# Step 2 — page through every row error. Limit/offset are bounded
# (limit max 100; default 20).
LIMIT=100
OFFSET=0
TOTAL_FAILED=$(echo "$STATUS" | jq -r .rowCountFailed)
while [ "${OFFSET}" -lt "${TOTAL_FAILED}" ]; do
PAGE=$(curl -fsS \
"${BASE_URL}/api/v1/monitoring/loan/imports/${IMPORT_ID}?errors=true&limit=${LIMIT}&offset=${OFFSET}" \
-H "Authorization: Bearer ${PAT}")
echo "$PAGE" | jq -c '.items[] | {rowNumber, errorCode, errorMessage}'
OFFSET=$((OFFSET + LIMIT))
done// TypeScript — inspect a partial / failed import's errors
const PAT = process.env.WAAFIR_PAT!;
const BASE_URL = process.env.WAAFIR_BASE_URL ?? "https://app.waafir.io";
const importId = process.argv[2];
if (!importId) throw new Error("usage: ts-node inspect.ts <importId>");
const auth = { Authorization: `Bearer ${PAT}` };
// Step 1 — terminal status + error summary.
const statusRes = await fetch(`${BASE_URL}/api/v1/monitoring/loan/imports/${importId}`, {
headers: auth,
});
type Status = {
status: string;
rowCountProcessed: number;
rowCountSucceeded: number;
rowCountFailed: number;
errorSummary: unknown;
};
const status = (await statusRes.json()) as Status;
console.log("status:", {
status: status.status,
rowCountProcessed: status.rowCountProcessed,
rowCountSucceeded: status.rowCountSucceeded,
rowCountFailed: status.rowCountFailed,
});
console.log("error summary (first ten):", status.errorSummary);
// Step 2 — page through every row error.
type RowError = {
rowNumber: number;
errorCode: string;
errorMessage: string;
rawRow: unknown;
createdAt: string;
};
const limit = 100;
for (let offset = 0; offset < status.rowCountFailed; offset += limit) {
const url = `${BASE_URL}/api/v1/monitoring/loan/imports/${importId}?errors=true&limit=${limit}&offset=${offset}`;
const pageRes = await fetch(url, { headers: auth });
const page = (await pageRes.json()) as { items: RowError[]; limit: number; offset: number };
for (const error of page.items) {
console.log({
rowNumber: error.rowNumber,
errorCode: error.errorCode,
errorMessage: error.errorMessage,
});
}
}# python — inspect a partial / failed import's errors
import os
import sys
import requests
PAT = os.environ["WAAFIR_PAT"]
BASE_URL = os.environ.get("WAAFIR_BASE_URL", "https://app.waafir.io")
import_id = sys.argv[1] if len(sys.argv) > 1 else None
if not import_id:
raise SystemExit("usage: python inspect.py <importId>")
auth = {"Authorization": f"Bearer {PAT}"}
# Step 1 — terminal status + error summary.
status = requests.get(
f"{BASE_URL}/api/v1/monitoring/loan/imports/{import_id}",
headers=auth,
timeout=30,
).json()
print("status:", {
"status": status["status"],
"rowCountProcessed": status["rowCountProcessed"],
"rowCountSucceeded": status["rowCountSucceeded"],
"rowCountFailed": status["rowCountFailed"],
})
print("error summary (first ten):", status.get("errorSummary"))
# Step 2 — page through every row error.
LIMIT = 100
offset = 0
total_failed = status["rowCountFailed"]
while offset < total_failed:
page = requests.get(
f"{BASE_URL}/api/v1/monitoring/loan/imports/{import_id}",
params={"errors": "true", "limit": LIMIT, "offset": offset},
headers=auth,
timeout=30,
).json()
for error in page["items"]:
print({
"rowNumber": error["rowNumber"],
"errorCode": error["errorCode"],
"errorMessage": error["errorMessage"],
})
offset += LIMITQué verificar
En una importación partial, la suma de rowCountSucceeded y rowCountFailed es igual a rowCountProcessed, y rowCountSucceeded es distinto de cero. En una importación failed, rowCountSucceeded es cero: o bien todas las filas a las que se llegó no superaron la validación, o bien el campo errorSummary.fatal describe un fallo a nivel del worker.
El campo rowNumber es la línea, indexada desde uno, de su archivo NDJSON. Relaciónela con sus filas de origen para encontrar los registros problemáticos, corríjalos y vuelva a enviar solo las filas corregidas o el archivo completo (use una clave de idempotencia nueva para la nueva intención; consulte la receta de reintentos).
El campo rawRow contiene la carga analizada tal como la recibió Waafir (para que pueda verificar que el formato enviado coincide con lo que generó su código); errorCode es un identificador estable de la regla de validación que se activó (para que pueda comparar grupos de errores con una lista de correcciones).