Разбор ошибок частичного сбоя после импорта
Этот рецепт показывает, как разобрать ошибки по строкам асинхронного импорта после того, как обработчик завершил работу. Эндпоинт статуса при каждом чтении возвращает небольшую выборку; режим постраничного просмотра ошибок того же эндпоинта выдаёт все ошибки с номером строки, кодом ошибки, сообщением об ошибке и исходными данными строки.
Когда приходит статус partial / failed
Одна некорректная строка никогда не прерывает импорт — обработчик Waafir проверяет каждую строку независимо, сохраняет каждую корректную и записывает запись об ошибке для каждой некорректной. Затем импорт переходит в один из двух конечных статусов:
partial— хотя бы одна строка обработана успешно и хотя бы одна строка завершилась ошибкой. Корректные строки записаны; некорректные можно запросить с помощью этого рецепта.failed— ни одна строка не обработана успешно. Либо все строки были некорректными, либо импорт столкнулся с фатальной ошибкой (некорректный NDJSON, сбой чтения файла, исключение в обработчике); в этом случаеerrorSummaryсодержит ошибку фатального типа.
Для обоих конечных состояний рецепт ниже — подходящий инструмент для детального разбора.
Структура данных об ошибках
Эндпоинт статуса (GET /api/v1/monitoring/loan/imports/{id}) возвращает поле errorSummary, которое имеет одну из двух структур в зависимости от того, что произошло:
- Ошибки на уровне строк (обычный случай для
partialи большинства прогоновfailed):errorSummaryимеет вид{ samples, totals }. Массивsamplesсодержит первые десять ошибок в виде{ rowNumber, errorCode, errorMessage, rawRow }. Полеtotalsсодержит общее количество. - Фатальные ошибки (импорт, прервавшийся до обработки хотя бы одной строки):
errorSummaryимеет вид{ fatal }— одна ошибка, описывающая сбой на уровне обработчика.
Чтобы получить больше первых десяти ошибок, используйте режим постраничного просмотра ошибок: GET /api/v1/monitoring/loan/imports/{id}?errors=true&limit=&offset=.
Рецепт
# 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Что проверить
Для импорта partial сумма rowCountSucceeded и rowCountFailed равна rowCountProcessed, а rowCountSucceeded не равно нулю. Для импорта failed значение rowCountSucceeded равно нулю — либо каждая доступная строка не прошла проверку, либо поле errorSummary.fatal описывает сбой на уровне обработчика.
Поле rowNumber — номер строки в вашем файле NDJSON, отсчитываемый с единицы. Сопоставьте его с исходными строками, чтобы найти проблемные записи, исправьте их и отправьте повторно либо только исправленные строки, либо весь файл (для нового намерения используйте новый ключ идемпотентности — см. рецепт о повторах).
Поле rawRow содержит разобранные данные в том виде, в каком их получил Waafir (чтобы можно было убедиться, что передаваемая структура совпадает с тем, что сгенерировал ваш код); errorCode — стабильный идентификатор сработавшего правила проверки (чтобы можно было сопоставлять группы ошибок со списком исправлений).