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 |
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 |
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, SKIPPED_ENTITY_ALREADY_EXISTS
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_QUOTA_EXCEEDED | Cota de criação excedida |
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 |
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.
