> ## 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.

# Fallos batch de transacciones

> Descarga reportes CSV o JSON con filas fallidas de un job batch de transacciones, incluyendo número de fila, códigos de error y mensajes de validación.

## Endpoints

```
GET https://api.gu1.ai/batch-import/transaction-jobs/{jobId}/failures.csv
GET https://api.gu1.ai/batch-import/transaction-jobs/{jobId}/failures
```

* **`…/failures.csv`** → descarga CSV (`Content-Disposition: attachment`)
* **`…/failures`** → cuerpo JSON

## Autenticación y permisos

```bash theme={null}
Authorization: Bearer TU_API_KEY
```

Requiere al menos uno de: **`transactions:create`**, **`entities:bulk_import`**, **`events:create`** (mismo middleware que el resto de `/batch-import`).

## Respuestas HTTP

| Código | Cuándo                                     |
| ------ | ------------------------------------------ |
| `200`  | Job encontrado (CSV o JSON)                |
| `401`  | Sin autenticación                          |
| `403`  | Sin permiso batch-import                   |
| `404`  | `jobId` inexistente o de otra organización |

## Columnas CSV

| Columna       | Descripción                                                                            |
| ------------- | -------------------------------------------------------------------------------------- |
| `external_id` | `externalId` de la transacción                                                         |
| `code`        | Código estable — [catálogo](/es/api-reference/bulk-imports/batch-import-failure-codes) |
| `error`       | Mensaje legible (igual que `message` en JSON)                                          |

Jobs legacy sin `code` en DB se normalizan al descargar cuando es posible. Si no hay fallos: CSV solo con header.

## Respuesta JSON

| Campo                                          | Tipo    | Descripción                                                                                                         |
| ---------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------- |
| `success`                                      | boolean | Siempre `true` si el job existe                                                                                     |
| `jobId`                                        | string  | Id del job                                                                                                          |
| `kind`                                         | string  | `transaction_batch`                                                                                                 |
| `status`                                       | string  | `queued`, `running`, `completed`, `failed`, …                                                                       |
| `totalItems`, `succeeded`, `failed`, `skipped` | number  | Contadores del job                                                                                                  |
| `failures`                                     | array   | `{ externalId, code, message }`                                                                                     |
| `jobFailure`                                   | object  | Solo si el **job entero** falló: `{ code, message, details? }` (p. ej. `INVALID_ENTITY_REFERENCES`)                 |
| `truncated`                                    | boolean | `true` si hay más de 500 fallos. La muestra se hidrata desde `failures.csv`; descargá el CSV para la lista completa |
| `failuresTotal`                                | number  | Total de filas fallidas informado por el artefacto del job                                                          |

```json theme={null}
{
  "success": true,
  "jobId": "abc-123",
  "kind": "transaction_batch",
  "status": "completed",
  "totalItems": 10,
  "succeeded": 9,
  "failed": 1,
  "skipped": 0,
  "failures": [
    {
      "externalId": "txn-009",
      "code": "CONSTRAINT_VIOLATION",
      "message": "…"
    }
  ],
  "truncated": false,
  "failuresTotal": 1
}
```

<Note>
  Con **`batchErrorHandling=rollback_all`** (default del upload multipart), un error de insert o refs de entidad inválidas (con validación estricta) aborta el batch: **0 filas creadas**; el detalle de refs va a **`failures.csv`** (S3) y `jobFailure`, no a un array gigante en metadata. Con **`continue_collect_errors`** o **`stop_keep_success`**, las refs inválidas y otros fallos de fila se registran por fila y las válidas sí se crean (o se detiene en el primero, según política).
</Note>

## Filas omitidas (duplicados)

```
GET https://api.gu1.ai/batch-import/transaction-jobs/{jobId}/skips.csv
```

Las filas contadas en `skipped` **no** son fallos: la transacción no se insertó porque ya existía
otra con el mismo `externalId` en tu organización. Este endpoint lista cuáles, para distinguir una
recarga de duplicados de un problema real.

| Columna       | Descripción                                   |
| ------------- | --------------------------------------------- |
| `external_id` | `externalId` de la transacción que ya existía |
| `reason`      | Siempre `DUPLICATE_EXTERNAL_ID`               |

Misma autenticación y permisos que los endpoints de fallos.

| Código | Cuándo                                                             |
| ------ | ------------------------------------------------------------------ |
| `200`  | Descarga CSV                                                       |
| `404`  | `jobId` inexistente, de otra organización, o `SKIPS_NOT_AVAILABLE` |

`SKIPS_NOT_AVAILABLE` significa que el job no tiene reporte guardado: jobs terminados antes de que
existiera este endpoint, jobs sin filas omitidas, y jobs enviados con `skipDuplicates=false` (los
duplicados los resuelve la base de datos y solo se cuentan, no se listan).

Ver también: [Códigos de fallo](/es/api-reference/bulk-imports/batch-import-failure-codes), [Importar transacciones](/es/api-reference/bulk-imports/import-transactions), [Historial unificado](/es/api-reference/bulk-imports/list-unified-history).