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

> Descarga en CSV o JSON las filas fallidas y omitidas (skips) de un job bulk de entidades, con motivos de error por fila para reprocesar en la API batch gu1.

## Endpoints

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

**Alias legacy CSV** (mismo archivo):

```
GET https://api.gu1.ai/entities/automatic/bulk/imports/{jobId}/failures.csv
```

* **`…/failures.csv`** → descarga CSV (solo filas `failed`)
* **`…/failures`** → JSON (`failures[]` + `skips[]` si aplica)

<Note>
  Este endpoint también devuelve **status** del job y contadores cuando **no** hay fallos por fila (`failures: []`). Para polling genérico en todos los tipos de import, preferir [Consultar estado de job batch](/es/api-reference/bulk-imports/get-batch-job-status).
</Note>

## Autenticación y permisos

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

Requiere al menos uno de: **`transactions:create`**, **`entities:bulk_import`**, **`events:create`**.

## Respuestas HTTP

| Código | Cuándo            |
| ------ | ----------------- |
| `200`  | Job encontrado    |
| `401`  | Sin autenticación |
| `403`  | Sin permiso       |
| `404`  | Job no encontrado |

## Columnas CSV (`failures.csv`)

Solo filas con **`outcome=failed`**.

| Columna         | Descripción                                                                            |
| --------------- | -------------------------------------------------------------------------------------- |
| `tax_id`        | Tax id de la fila                                                                      |
| `type`          | `person` o `company`                                                                   |
| `outcome`       | Siempre `failed` en este export                                                        |
| `code`          | Código estable — [catálogo](/es/api-reference/bulk-imports/batch-import-failure-codes) |
| `error_message` | Detalle legible                                                                        |

<Warning>
  **Duplicado por taxId (bulk manual default):** mismo taxId + mismo tipo → **`skipped_existing`**, código **`SKIPPED_DUPLICATE_TAX_ID`**. **No** aparece en `failures.csv`. Consultá JSON `skips[]` o el reporte completo del job.
</Warning>

## Respuesta JSON

Incluye **`failures[]`** (solo `failed`) y, si aplica, **`skips[]`** / **`skipsTotal`** (filas omitidas, no errores).

```json theme={null}
{
  "success": true,
  "jobId": "…",
  "kind": "entity_automatic",
  "status": "completed",
  "totalItems": 100,
  "succeeded": 97,
  "failed": 2,
  "skipped": 1,
  "failures": [
    {
      "taxId": "20123456789",
      "type": "company",
      "outcome": "failed",
      "code": "DUPLICATE_EXTERNAL_ID",
      "message": "An entity with external ID \"X\" already exists…"
    }
  ],
  "truncated": false,
  "failuresTotal": 2,
  "skips": [
    {
      "taxId": "30111222333",
      "type": "person",
      "outcome": "skipped_existing",
      "code": "SKIPPED_DUPLICATE_TAX_ID"
    }
  ],
  "skipsTotal": 1
}
```

| Campo skip                      | Significado                         |
| ------------------------------- | ----------------------------------- |
| `SKIPPED_DUPLICATE_TAX_ID`      | Bulk manual: taxId+tipo ya existía  |
| `SKIPPED_ENTITY_ALREADY_EXISTS` | Bulk automático: entidad ya existía |

Ver también: [Importar entidades](/es/api-reference/bulk-imports/import-entities), [Códigos de fallo](/es/api-reference/bulk-imports/batch-import-failure-codes).