Códigos de falha batch

Endpoints para baixar falhas

Recurso	CSV	JSON
Transações	`GET /batch-import/transaction-jobs/{jobId}/failures.csv`	GET …/failures
Eventos	`GET /batch-import/user-event-jobs/{jobId}/failures.csv`	GET …/failures
Entidades	`GET /batch-import/entity-jobs/{jobId}/failures.csv`	GET …/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 → `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.

Começando

SDK

Casos de Uso

Webhooks

Workflows

Monitoramento (entidades)

Pessoa

Mensagens

Empresa

Dispositivos

Eventos

Conheça Seu Cliente (KYC)

Transações

Métodos de Pagamento

Regras

Listas de dados

Matriz de Risco

Alertas

Investigações

Ingestão de Dados

Importações em lote

Enriquecimento

Serviços

Integrações

Tutoriais Interativos

Códigos de falha batch

Endpoints para baixar falhas

Modelo de três camadas

Três resultados possíveis por linha (entidades)

Duplicado por `taxId`

Códigos de falha por linha (`failures[]` / failures.csv)

Códigos de skip (`skips[]` — só entidades, não é falha)

Códigos de job completo (`jobFailure`)

Matriz de cenários (FAQ cliente)

Cenários reproduzíveis (testes)

Limites

​Endpoints para baixar falhas

​Modelo de três camadas

​Três resultados possíveis por linha (entidades)

​Duplicado por taxId

​Códigos de falha por linha (failures[] / failures.csv)

​Códigos de skip (skips[] — só entidades, não é falha)

​Códigos de job completo (jobFailure)

​Matriz de cenários (FAQ cliente)

​Cenários reproduzíveis (testes)

​Limites

Endpoints para baixar falhas

Modelo de três camadas

Três resultados possíveis por linha (entidades)

Duplicado por `taxId`

Códigos de falha por linha (`failures[]` / failures.csv)

Códigos de skip (`skips[]` — só entidades, não é falha)

Códigos de job completo (`jobFailure`)

Matriz de cenários (FAQ cliente)

Cenários reproduzíveis (testes)

Limites