Waafir
Esta página é uma tradução automática pendente de revisão humana. Pode conter erros.

Inspecionar erros de falha parcial após uma importação

Esta receita mostra como inspecionar os erros por linha de uma importação assíncrona depois que o worker termina. O endpoint de status traz uma pequena amostra a cada leitura; o modo de erros paginados do mesmo endpoint retorna todos os erros, com número da linha, código de erro, mensagem de erro e o payload bruto da linha.

Quando chega o status partial / failed

Uma única linha inválida nunca aborta uma importação — o worker do Waafir valida cada linha de forma independente, grava todas as válidas e registra um erro por linha para cada uma inválida. A importação então se acomoda em um de dois status terminais:

  • partial — pelo menos uma linha teve sucesso e pelo menos uma linha falhou. As linhas válidas foram gravadas; as inválidas podem ser consultadas com esta receita.
  • failed — nenhuma linha teve sucesso. Ou todas as linhas eram inválidas, ou a importação encontrou um erro fatal (NDJSON malformado, falha na leitura do arquivo, exceção do worker); nesse caso, o errorSummary traz um erro no formato fatal.

Para ambos os estados terminais, a receita abaixo é a ferramenta certa para investigar em detalhe.

O formato da superfície de erros

O endpoint de status (GET /api/v1/monitoring/loan/imports/{id}) retorna um campo errorSummary com dois formatos, conforme o que aconteceu:

  • Erros por linha (o caso comum para partial e para a maioria das execuções failed): errorSummary é { samples, totals }. O array samples traz os dez primeiros erros como { rowNumber, errorCode, errorMessage, rawRow }. O campo totals apresenta uma contagem agregada.
  • Erros fatais (uma importação que falhou antes de processar qualquer linha): errorSummary é { fatal } — um único erro que descreve a falha no nível do worker.

Para além dos dez primeiros erros, percorra o modo de erros paginados: GET /api/v1/monitoring/loan/imports/{id}?errors=true&limit=&offset=.

A receita

# 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

O que verificar

Para uma importação partial, a soma de rowCountSucceeded e rowCountFailed é igual a rowCountProcessed, e rowCountSucceeded é diferente de zero. Para uma importação failed, rowCountSucceeded é zero — todas as linhas alcançáveis falharam na validação, ou o campo errorSummary.fatal descreve uma falha no nível do worker.

O campo rowNumber é a linha, com índice iniciado em um, no seu arquivo NDJSON. Mapeie-o de volta às linhas de origem para encontrar os registros problemáticos, corrija-os e reenvie apenas as linhas corrigidas ou o arquivo inteiro (use uma nova chave de idempotência para a nova intenção — consulte a receita de novas tentativas).

O campo rawRow traz o payload interpretado tal como o Waafir o recebeu (para que você possa verificar se o formato enviado corresponde ao que o seu código gerou); o errorCode é um identificador estável da regra de validação acionada (para que você possa associar grupos de erros a uma lista de correções).