Endpoints para descargar fallos
| Recurso | CSV | JSON |
|---|
| Transacciones | GET /batch-import/transaction-jobs/{jobId}/failures.csv | GET …/failures |
| Eventos | GET /batch-import/user-event-jobs/{jobId}/failures.csv | GET …/failures |
| Entidades | GET /batch-import/entity-jobs/{jobId}/failures.csv | GET …/failures |
GET /entities/automatic/bulk/imports/{jobId}/failures.csv.
…/failures.csv → archivo CSV descargable (Content-Type: text/csv)…/failures → JSON (Content-Type: application/json)
Modelo de tres capas
| Capa | Cuándo | Dónde leer |
|---|
| Pre-job | Request rechazado antes de devolver jobId (400) | Body HTTP (error.code) |
| Job completo | Job abortado (status: failed) | Historial unificado → workerError, metadata.apiError; JSON → jobFailure |
| Por fila | Algunas filas fallaron (failed > 0, job puede ser completed) | CSV/JSON de fallos según tipo de job |
code (máquina) y message (humano). Jobs legacy pueden tener solo error en texto libre; la API normaliza al leer.
Tres resultados posibles por fila (entidades)
| Resultado | outcome | ¿Va a failures.csv? | Dónde se ve |
|---|
| Creada | created | No | Job succeeded, reporte completo |
| Omitida (skip) | skipped_existing | No | Job skipped / skippedExisting, reporte completo, JSON skips[] |
| Fallida | failed | Sí | Job failed, failures.csv / JSON failures[] |
Duplicate por taxId — el caso que confunde
Bulk manual (default): duplicateTaxIdPolicy: skip_existing.
- Mismo
taxId + mismo type ya existe → skipped_existing, código SKIPPED_DUPLICATE_TAX_ID
- No aparece en
failures.csv (no es error)
- Contador:
skippedExisting en historial unificado
Bulk automático:
- Entidad principal ya existía →
skipped_existing, código SKIPPED_ENTITY_ALREADY_EXISTS
Cuándo sí es fallo (failed):
| Situación | Código batch |
|---|
| Mismo taxId pero tipo distinto (person vs company) | TAX_ID_TYPE_MISMATCH |
Mismo taxId+mismo tipo con política error (API unitaria; no default bulk) | DUPLICATE_TAX_ID |
Mismo externalId | DUPLICATE_EXTERNAL_ID |
Códigos de fallo por fila (failures[] / failures.csv)
| Código | Significado |
|---|
VALIDATION_ERROR | Validación Zod / esquema antes de persistir |
PROCESSING_ERROR | Error inesperado al procesar la fila |
ENTITY_NOT_FOUND | Entidad referenciada no existe en la org |
INVALID_RISK_MATRIX | Matriz inválida o de otra org |
CREATION_QUOTA_EXCEEDED | Cuota de creación excedida |
DATABASE_INSERT_ERROR | Insert rechazado por PG (sin clasificar) |
DUPLICATE_EXTERNAL_ID | Mismo externalId ya existe |
DUPLICATE_TAX_ID | Mismo taxId + tipo (error duro) |
TAX_ID_TYPE_MISMATCH | taxId registrado bajo otro tipo de entidad |
CONSTRAINT_VIOLATION | Otro constraint PG (FK, check, unique) |
MISSING_COUNTRY | Fila sin país ISO2 válido |
INVALID_COUNTRY | País no permitido para el modo (p. ej. automatic ≠ AR/BR/CL) |
ENRICHMENT_FAILED | Proveedor enrichment falló |
CREATION_FAILED | No se pudo crear la entidad |
Códigos de skip (skips[] — solo entidades, no es fallo)
| Código | Significado |
|---|
SKIPPED_DUPLICATE_TAX_ID | Bulk manual: taxId+tipo ya existía, fila omitida |
SKIPPED_ENTITY_ALREADY_EXISTS | Bulk automático: entidad ya existía |
Matriz de riesgo / reglas de negocio: la ejecución de reglas ocurre después de crear la fila. Los resultados de reglas no aparecen en failures.csv / JSON failures[] y no revierten la fila. Usá alertas, score de riesgo y timelines de auditoría.
Códigos de job completo (jobFailure)
| Código | Significado |
|---|
INVALID_ENTITY_REFERENCES | Batch txn: validateExistingEntity=true y refs origen/destino sin resolver — ninguna fila creada |
TOO_MANY_ITEMS | Archivo supera límite del plan |
CSV_PARSE_ERROR | CSV no parseable o mapeo falló |
MAPPING_VALIDATION_ERROR | Mapeo guardado o preflight validate-csv falló |
MISSING_REQUIRED_FIELD | Campo multipart / fila requerido faltante antes de encolar |
COOPERATIVE_CANCEL | Job cancelado durante procesamiento |
WORKER_ERROR | Error no manejado del worker |
Matriz de escenarios (FAQ cliente)
| Escenario | ¿En failures por fila? | Código / ubicación típica |
|---|
| Columna CSV faltante (pre-parse) | No | 400 antes del job |
| Ref entidad inválida (txn batch, validación default) | No | Job INVALID_ENTITY_REFERENCES |
Duplicate txn externalId con skipDuplicates=true | No | Contado como skipped |
Duplicate entity externalId (import manual) | Sí | DUPLICATE_EXTERNAL_ID |
Duplicate entity taxId (mismo tipo, bulk default) | No | skipped_existing → SKIPPED_DUPLICATE_TAX_ID en skips[] |
Duplicate entity taxId (tipo distinto) | Sí | TAX_ID_TYPE_MISMATCH |
| Fallo enrichment (entity automatic) | Sí | ENRICHMENT_FAILED |
| Campo inválido en user event | Sí | VALIDATION_ERROR |
| Error evaluación reglas / matriz | No | Fila igual se crea |
Escenarios reproducibles (pruebas)
User events (fallos por fila más simples): CSV válido + mapping; una fila con campo requerido vacío → GET …/user-event-jobs/{jobId}/failures.
Entidades (manual): crear entidad con external_id=X, importar otra fila con mismo external_id → DUPLICATE_EXTERNAL_ID.
Transacciones (job-level): validateExistingEntity=true + originExternalId=DOES_NOT_EXIST → job failed, jobFailure.code=INVALID_ENTITY_REFERENCES.
Transacciones (row-level): batchErrorHandling=continue_collect_errors + filas válidas mezcladas con violaciones de constraint → entradas en endpoint de fallos.
Límites
- Máx. 500 fallos por fila persistidos por job batch de transacciones (CSV + JSON pueden truncar; JSON expone
truncated + failuresTotal).
Reporte completo por email (entidades): todas las filas (created, skipped_existing, failed) con columna code.
Ver también: Importaciones masivas — overview.
