> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Códigos de fallo batch

> Códigos estables de error para fallos por fila, skips y a nivel de job en importaciones batch de transacciones, entidades y eventos de usuario.

## Endpoints para descargar fallos

| Recurso       | CSV                                                       | JSON                                                                            |
| ------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------- |
| Transacciones | `GET /batch-import/transaction-jobs/{jobId}/failures.csv` | [GET …/failures](/es/api-reference/bulk-imports/get-transaction-batch-failures) |
| Eventos       | `GET /batch-import/user-event-jobs/{jobId}/failures.csv`  | [GET …/failures](/es/api-reference/bulk-imports/get-user-event-batch-failures)  |
| Entidades     | `GET /batch-import/entity-jobs/{jobId}/failures.csv`      | [GET …/failures](/es/api-reference/bulk-imports/get-entity-batch-failures)      |

Alias legacy CSV entidades: `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](/es/api-reference/bulk-imports/list-unified-history) → `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                                                                                                 |

Cada fallo por fila incluye **`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`**
  * **`refresh: false`**: **`SKIPPED_ENTITY_ALREADY_EXISTS`** — sin re-enriquecimiento
  * **`refresh: true`**: **`SKIPPED_ENTITY_ALREADY_EXISTS_REFRESHED`** — creación omitida, re-enriquecimiento ejecutado

**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_CONTRACT_QUOTA_EXCEEDED` | Cuota contractual de creación excedida.                                                 |
| `CREATION_QUOTA_EXCEEDED`          | Alias deprecado de `CREATION_CONTRACT_QUOTA_EXCEEDED` (solo `failures.csv` históricos). |
| `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, refresh off                               |
| `SKIPPED_ENTITY_ALREADY_EXISTS_REFRESHED` | Bulk automático: entidad ya existía, refresh on — re-enriquecimiento ejecutado |

<Note>
  **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.
</Note>

## 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](/es/api-reference/bulk-imports/overview).