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

# Entity batch failures

> Download failed and skipped rows for a bulk entity import job as CSV or JSON, with row-level error reasons for reprocessing in the gu1 batch API.

## Endpoints

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

Legacy CSV alias (same file):

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

* **`…/failures.csv`** → CSV download (failed rows only)
* **`…/failures`** → JSON (`failures[]` + `skips[]` when applicable)

<Note>
  This endpoint also returns job **status** and counters when there are **no** row failures (`failures: []`). For generic polling across import kinds, prefer [Get batch job status](/en/api-reference/bulk-imports/get-batch-job-status).
</Note>

## Authentication

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

Requires at least one of: **`transactions:create`**, **`entities:bulk_import`**, **`events:create`**.

## HTTP responses

| Status | When               |
| ------ | ------------------ |
| `200`  | Job found          |
| `401`  | Not authenticated  |
| `403`  | Missing permission |
| `404`  | Job not found      |

## CSV columns

| Column          | Description                                                                                          |
| --------------- | ---------------------------------------------------------------------------------------------------- |
| `tax_id`        | Row tax id                                                                                           |
| `type`          | `person` or `company`                                                                                |
| `outcome`       | Always `failed` in this export                                                                       |
| `code`          | Stable failure code — see [Failure codes](/en/api-reference/bulk-imports/batch-import-failure-codes) |
| `error_message` | Human-readable detail                                                                                |

<Warning>
  **Duplicate taxId (bulk manual default):** same taxId + same type → **`skipped_existing`**, code **`SKIPPED_DUPLICATE_TAX_ID`**. Does **not** appear in `failures.csv`. Use JSON `skips[]` or the full job report.
</Warning>

## JSON response

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

| Skip code                       | Meaning                                 |
| ------------------------------- | --------------------------------------- |
| `SKIPPED_DUPLICATE_TAX_ID`      | Manual bulk: taxId+type already existed |
| `SKIPPED_ENTITY_ALREADY_EXISTS` | Automatic bulk: entity already existed  |

`failures.csv` contains **only** `outcome=failed` rows.

See also: [Import entities (CSV)](/en/api-reference/bulk-imports/import-entities), [Failure codes](/en/api-reference/bulk-imports/batch-import-failure-codes).