Inspecter les erreurs d'échec partiel après un import
Cette recette montre comment inspecter les erreurs ligne par ligne d'un import asynchrone une fois le traitement du worker terminé. L'endpoint de statut expose un court échantillon à chaque lecture ; le mode d'erreurs paginées du même endpoint restitue chaque erreur avec son numéro de ligne, son code d'erreur, son message d'erreur et le contenu brut de la ligne.
Quand le statut partiel ou en échec arrive
Une seule ligne invalide n'interrompt jamais un import — le worker de Waafir valide chaque ligne indépendamment, enregistre toutes les lignes valides et écrit un enregistrement d'erreur pour chaque ligne invalide. L'import se stabilise ensuite dans l'un des deux statuts finaux suivants :
partial— au moins une ligne a réussi et au moins une ligne a échoué. Les lignes valides ont été enregistrées ; les lignes invalides peuvent être consultées grâce à cette recette.failed— aucune ligne n'a réussi. Soit toutes les lignes étaient invalides, soit l'import a rencontré une erreur fatale (NDJSON mal formé, échec de lecture du fichier, exception du worker) ; dans ce cas,errorSummarycontient une erreur de type fatal.
Pour ces deux états finaux, la recette ci-dessous est l'outil adapté pour approfondir.
Structure des informations d'erreur
L'endpoint de statut (GET /api/v1/monitoring/loan/imports/{id}) renvoie un champ errorSummary qui prend deux formes selon ce qui s'est passé :
- Erreurs de ligne (le cas courant pour
partialet la plupart des exécutionsfailed) :errorSummaryvaut{ samples, totals }. Le tableausamplescontient les dix premières erreurs sous la forme{ rowNumber, errorCode, errorMessage, rawRow }. Le champtotalsexpose un décompte agrégé. - Erreurs fatales (un import interrompu avant d'avoir traité la moindre ligne) :
errorSummaryvaut{ fatal }— une erreur unique décrivant la défaillance au niveau du worker.
Au-delà des dix premières erreurs, parcourez le mode d'erreurs paginées : GET /api/v1/monitoring/loan/imports/{id}?errors=true&limit=&offset=.
La recette
# 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 += LIMITCe qu'il faut vérifier
Pour un import partial, la somme de rowCountSucceeded et rowCountFailed est égale à rowCountProcessed, et rowCountSucceeded est non nul. Pour un import failed, rowCountSucceeded vaut zéro — chaque ligne atteignable a échoué à la validation, ou bien le champ errorSummary.fatal décrit une défaillance au niveau du worker.
Le champ rowNumber est le numéro de ligne (à partir de un) dans votre fichier NDJSON. Faites-le correspondre à vos lignes sources pour retrouver les enregistrements fautifs, corrigez-les, puis soumettez à nouveau soit les seules lignes corrigées, soit le fichier entier (utilisez une nouvelle clé d'idempotence pour cette nouvelle intention — voir la recette sur les relances).
Le champ rawRow contient le contenu analysé tel que Waafir l'a reçu (ce qui vous permet de vérifier que le format transmis correspond à ce que votre code a généré) ; errorCode est un identifiant stable de la règle de validation déclenchée (ce qui vous permet de rapprocher des groupes d'erreurs d'une liste de corrections).