> ## 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. # Códigos de falha batch > Códigos estáveis de erro para falhas por linha, skips e a nível de job em importações batch de transações, entidades e eventos de usuário. ## Endpoints para baixar falhas | Recurso | CSV | JSON | | ---------- | --------------------------------------------------------- | ------------------------------------------------------------------------------- | | Transações | `GET /batch-import/transaction-jobs/{jobId}/failures.csv` | [GET …/failures](/pt/api-reference/bulk-imports/get-transaction-batch-failures) | | Eventos | `GET /batch-import/user-event-jobs/{jobId}/failures.csv` | [GET …/failures](/pt/api-reference/bulk-imports/get-user-event-batch-failures) | | Entidades | `GET /batch-import/entity-jobs/{jobId}/failures.csv` | [GET …/failures](/pt/api-reference/bulk-imports/get-entity-batch-failures) | Alias legacy CSV entidades: `GET /entities/automatic/bulk/imports/{jobId}/failures.csv`. * **`…/failures.csv`** → arquivo CSV para download (`Content-Type: text/csv`) * **`…/failures`** → JSON (`Content-Type: application/json`) ## Modelo de três camadas | Camada | Quando | Onde ler | | ---------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | **Pre-job** | Request rejeitado antes de retornar `jobId` (`400`) | Body HTTP (`error.code`) | | **Job completo** | Job abortado (`status: failed`) | [Histórico unificado](/pt/api-reference/bulk-imports/list-unified-history) → `workerError`, `metadata.apiError`; JSON → `jobFailure` | | **Por linha** | Algumas linhas falharam (`failed > 0`, job pode ser `completed`) | CSV/JSON de falhas por tipo de job | Cada falha por linha inclui **`code`** (máquina) e **`message`** (humano). Jobs legacy podem ter só `error` em texto livre; a API normaliza na leitura. ## Três resultados possíveis por linha (entidades) | Resultado | `outcome` | Vai para failures.csv? | Onde ver | | ------------------ | ------------------ | ---------------------- | --------------------------------------------------------------------- | | **Criada** | `created` | Não | Job `succeeded`, relatório completo | | **Omitida (skip)** | `skipped_existing` | **Não** | Job `skipped` / `skippedExisting`, relatório completo, JSON `skips[]` | | **Falhou** | `failed` | **Sim** | Job `failed`, failures.csv / JSON `failures[]` | ### Duplicado por `taxId` **Bulk manual (default):** `duplicateTaxIdPolicy: skip_existing`. * Mesmo `taxId` + mesmo `type` já existe → **`skipped_existing`**, código **`SKIPPED_DUPLICATE_TAX_ID`** * **Não** aparece em `failures.csv` * Contador: `skippedExisting` no histórico unificado **Bulk automático:** entidade principal já existia → **`skipped_existing`** * **`refresh: false`**: **`SKIPPED_ENTITY_ALREADY_EXISTS`** — sem re-enriquecimento * **`refresh: true`**: **`SKIPPED_ENTITY_ALREADY_EXISTS_REFRESHED`** — criação omitida, re-enriquecimento executado **Quando é falha (`failed`):** | Situação | Código batch | | ---------------------------------------------------- | ----------------------- | | Mesmo taxId, **tipo diferente** (person vs company) | `TAX_ID_TYPE_MISMATCH` | | Mesmo taxId+tipo com política `error` (API unitária) | `DUPLICATE_TAX_ID` | | Mesmo `externalId` | `DUPLICATE_EXTERNAL_ID` | ## Códigos de falha por linha (`failures[]` / failures.csv) | Código | Significado | | ---------------------------------- | ------------------------------------------------------------------------------------------ | | `VALIDATION_ERROR` | Validação Zod / esquema antes de persistir | | `PROCESSING_ERROR` | Erro inesperado ao processar a linha | | `ENTITY_NOT_FOUND` | Entidade referenciada não existe na org | | `INVALID_RISK_MATRIX` | Matriz inválida ou de outra org | | `CREATION_CONTRACT_QUOTA_EXCEEDED` | Cota contratual de criação excedida. | | `CREATION_QUOTA_EXCEEDED` | Alias depreciado de `CREATION_CONTRACT_QUOTA_EXCEEDED` (apenas `failures.csv` históricos). | | `DATABASE_INSERT_ERROR` | Insert rejeitado pelo PG (sem classificar) | | `DUPLICATE_EXTERNAL_ID` | Mesmo `externalId` já existe | | `DUPLICATE_TAX_ID` | Mesmo taxId + tipo (erro duro) | | `TAX_ID_TYPE_MISMATCH` | taxId registrado sob outro tipo de entidade | | `CONSTRAINT_VIOLATION` | Outro constraint PG (FK, check, unique) | | `MISSING_COUNTRY` | Linha sem país ISO2 válido | | `INVALID_COUNTRY` | País não permitido para o modo (p. ex. automatic ≠ AR/BR/CL) | | `ENRICHMENT_FAILED` | Provedor enrichment falhou | | `CREATION_FAILED` | Não foi possível criar a entidade | ## Códigos de skip (`skips[]` — só entidades, não é falha) | Código | Significado | | ----------------------------------------- | ------------------------------------------------------------------------------ | | `SKIPPED_DUPLICATE_TAX_ID` | Bulk manual: taxId+tipo já existia, linha omitida | | `SKIPPED_ENTITY_ALREADY_EXISTS` | Bulk automático: entidade já existia, refresh off | | `SKIPPED_ENTITY_ALREADY_EXISTS_REFRESHED` | Bulk automático: entidade já existia, refresh on — re-enriquecimento executado | **Matriz de risco / regras de negócio:** a execução de regras ocorre **depois** de criar a linha. Resultados de regras **não** aparecem em `failures.csv` / JSON `failures[]` e não revertem a linha. Use alertas, score de risco e timelines de auditoria. ## Códigos de job completo (`jobFailure`) | Código | Significado | | --------------------------- | -------------------------------------------------------------------------------------------------------- | | `INVALID_ENTITY_REFERENCES` | Batch txn: `validateExistingEntity=true` e refs origem/destino não resolvidas — **nenhuma linha criada** | | `TOO_MANY_ITEMS` | Arquivo excede limite do plano | | `CSV_PARSE_ERROR` | CSV não parseável ou mapeamento falhou | | `MAPPING_VALIDATION_ERROR` | Mapeamento salvo ou preflight validate-csv falhou | | `MISSING_REQUIRED_FIELD` | Campo multipart / linha obrigatório faltando antes de enfileirar | | `COOPERATIVE_CANCEL` | Job cancelado durante processamento | | `WORKER_ERROR` | Erro não tratado do worker | ## Matriz de cenários (FAQ cliente) | Cenário | Em `failures` por linha? | Código / localização típica | | ---------------------------------------------------- | ------------------------ | ------------------------------------------------------------ | | Coluna CSV faltando (pre-parse) | Não | `400` antes do job | | Ref entidade inválida (txn batch, validação default) | Não | Job `INVALID_ENTITY_REFERENCES` | | Duplicado txn `externalId` com `skipDuplicates=true` | Não | Contado como `skipped` | | Duplicado entity `externalId` (import manual) | Sim | `DUPLICATE_EXTERNAL_ID` | | Duplicado entity `taxId` (mesmo tipo, bulk default) | Não | `skipped_existing` → `SKIPPED_DUPLICATE_TAX_ID` em `skips[]` | | Duplicado entity `taxId` (tipo diferente) | Sim | `TAX_ID_TYPE_MISMATCH` | | Falha enrichment (entity automatic) | Sim | `ENRICHMENT_FAILED` | | Campo inválido em user event | Sim | `VALIDATION_ERROR` | | Erro avaliação regras / matriz | Não | Linha ainda é criada | ## Cenários reproduzíveis (testes) **User events:** CSV válido + mapping; uma linha com campo obrigatório vazio → `GET …/user-event-jobs/{jobId}/failures`. **Entidades (manual):** criar entidade com `external_id=X`, importar outra linha com mesmo `external_id` → `DUPLICATE_EXTERNAL_ID`. **Transações (job-level):** `validateExistingEntity=true` + `originExternalId=DOES_NOT_EXIST` → job `failed`, `jobFailure.code=INVALID_ENTITY_REFERENCES`. **Transações (row-level):** `batchErrorHandling=continue_collect_errors` + linhas válidas misturadas com violações de constraint → entradas no endpoint de falhas. ## Limites * Máx. **500** falhas por linha persistidas por job batch de transações (CSV + JSON podem truncar; JSON expõe `truncated` + `failuresTotal`). Relatório completo por email (entidades): todas as linhas (`created`, `skipped_existing`, `failed`) com coluna `code`. Ver também: [Importações em lote — overview](/pt/api-reference/bulk-imports/overview).