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

# Falhas batch de entidades

> Baixe em CSV ou JSON as linhas com falha e skips de um job bulk de entidades, com motivos de erro por linha para reprocessar na API batch da 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** (mesmo arquivo):

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

* **`…/failures.csv`** → download CSV (somente linhas `failed`)
* **`…/failures`** → JSON (`failures[]` + `skips[]` quando aplicável)

<Note>
  Este endpoint também retorna **status** do job e contadores quando **não** há falhas por linha (`failures: []`). Para polling genérico em todos os tipos de import, prefira [Consultar status do job batch](/pt/api-reference/bulk-imports/get-batch-job-status).
</Note>

## Autenticação e permissões

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

Requer pelo menos um de: **`transactions:create`**, **`entities:bulk_import`**, **`events:create`**.

## Respostas HTTP

| Código | Quando             |
| ------ | ------------------ |
| `200`  | Job encontrado     |
| `401`  | Sem autenticação   |
| `403`  | Sem permissão      |
| `404`  | Job não encontrado |

## Colunas CSV (`failures.csv`)

Somente linhas com **`outcome=failed`**.

| Coluna          | Descrição                                                                              |
| --------------- | -------------------------------------------------------------------------------------- |
| `tax_id`        | Tax id da linha                                                                        |
| `type`          | `person` ou `company`                                                                  |
| `outcome`       | Sempre `failed` neste export                                                           |
| `code`          | Código estável — [catálogo](/pt/api-reference/bulk-imports/batch-import-failure-codes) |
| `error_message` | Detalhe legível                                                                        |

<Warning>
  **Duplicado por taxId (bulk manual default):** mesmo taxId + mesmo tipo → **`skipped_existing`**, código **`SKIPPED_DUPLICATE_TAX_ID`**. **Não** aparece em `failures.csv`. Consulte JSON `skips[]` ou o relatório completo do job.
</Warning>

## Resposta JSON

Inclui **`failures[]`** (somente `failed`) e, se aplicável, **`skips[]`** / **`skipsTotal`** (linhas omitidas, não erros).

```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
}
```

| Código skip                     | Significado                          |
| ------------------------------- | ------------------------------------ |
| `SKIPPED_DUPLICATE_TAX_ID`      | Bulk manual: taxId+tipo já existia   |
| `SKIPPED_ENTITY_ALREADY_EXISTS` | Bulk automático: entidade já existia |

`failures.csv` contém **somente** linhas `outcome=failed`. Duplicados taxId omitidos aparecem em JSON `skips[]` e no relatório completo por email, não em `failures.csv`.

Ver também: [Importar entidades](/pt/api-reference/bulk-imports/import-entities), [Códigos de falha](/pt/api-reference/bulk-imports/batch-import-failure-codes).