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

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, errorSummary contiene 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 partial y en la mayoría de las failed): errorSummary es { samples, totals }. El array samples contiene los diez primeros errores como { rowNumber, errorCode, errorMessage, rawRow }. El campo totals muestra un recuento agregado.
  • Errores fatales (una importación que se detuvo antes de procesar ninguna fila): errorSummary es { 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 += LIMIT

Qué 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).