> ## 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 transações

> Baixe relatórios CSV ou JSON com linhas de transações que falharam em um job batch, incluindo número da linha, códigos de erro e mensagens de validação.

## 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`** → download CSV (`Content-Disposition: attachment`)
* **`…/failures`** → corpo JSON

## 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 (CSV ou JSON)                |
| `401`  | Sem autenticação                            |
| `403`  | Sem permissão batch-import                  |
| `404`  | `jobId` inexistente ou de outra organização |

## Colunas CSV

| Coluna        | Descrição                                                                              |
| ------------- | -------------------------------------------------------------------------------------- |
| `external_id` | `externalId` da transação                                                              |
| `code`        | Código estável — [catálogo](/pt/api-reference/bulk-imports/batch-import-failure-codes) |
| `error`       | Mensagem legível (igual a `message` no JSON)                                           |

Jobs legacy sem `code` na DB são normalizados no download quando possível. Se não houver falhas: CSV só com header.

## Resposta JSON

| Campo                                          | Tipo    | Descrição                                                                                                       |
| ---------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------- |
| `success`                                      | boolean | Sempre `true` se o job existe                                                                                   |
| `jobId`                                        | string  | Id do job                                                                                                       |
| `kind`                                         | string  | `transaction_batch`                                                                                             |
| `status`                                       | string  | `queued`, `running`, `completed`, `failed`, …                                                                   |
| `totalItems`, `succeeded`, `failed`, `skipped` | number  | Contadores do job                                                                                               |
| `failures`                                     | array   | `{ externalId, code, message }`                                                                                 |
| `jobFailure`                                   | object  | Se o **job inteiro** falhou: `{ code, message, details? }` (p. ex. `INVALID_ENTITY_REFERENCES`)                 |
| `truncated`                                    | boolean | `true` se houver mais de 500 falhas. A amostra é hidratada do `failures.csv`; baixe o CSV para a lista completa |
| `failuresTotal`                                | number  | Total de linhas com falha informado pelo artefato do 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>
  Com **`batchErrorHandling=rollback_all`** (padrão do upload multipart), um erro de insert ou refs de entidade inválidas (validação estrita) aborta o batch: **0 linhas criadas**; o detalhe das refs vai para **`failures.csv`** (S3) e `jobFailure`, não para um array gigante em metadata. Com **`continue_collect_errors`** ou **`stop_keep_success`**, refs inválidas e outros falhas por linha são registradas por linha e as válidas são criadas (ou o processamento para no primeiro erro, conforme a política).
</Note>

## Linhas ignoradas (duplicatas)

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

As linhas contadas em `skipped` **não** são falhas: a transação não foi inserida porque já existia
outra com o mesmo `externalId` na sua organização. Este endpoint lista quais, para diferenciar um
reenvio de duplicatas de um problema real.

| Coluna        | Descrição                                |
| ------------- | ---------------------------------------- |
| `external_id` | `externalId` da transação que já existia |
| `reason`      | Sempre `DUPLICATE_EXTERNAL_ID`           |

Mesma autenticação e permissões dos endpoints de falhas.

| Código | Quando                                                              |
| ------ | ------------------------------------------------------------------- |
| `200`  | Download CSV                                                        |
| `404`  | `jobId` inexistente, de outra organização, ou `SKIPS_NOT_AVAILABLE` |

`SKIPS_NOT_AVAILABLE` significa que o job não tem relatório salvo: jobs finalizados antes deste
endpoint existir, jobs sem linhas ignoradas, e jobs enviados com `skipDuplicates=false` (as
duplicatas são resolvidas pelo banco e apenas contadas, não listadas).

Ver também: [Códigos de falha](/pt/api-reference/bulk-imports/batch-import-failure-codes), [Importar transações](/pt/api-reference/bulk-imports/import-transactions), [Histórico unificado](/pt/api-reference/bulk-imports/list-unified-history).