Batch import failure codes

Failure Download Endpoints

Resource	CSV	JSON
Transactions	`GET /batch-import/transaction-jobs/{jobId}/failures.csv`	GET …/failures
User events	`GET /batch-import/user-event-jobs/{jobId}/failures.csv`	GET …/failures
Entities	`GET /batch-import/entity-jobs/{jobId}/failures.csv`	GET …/failures

Legacy entity CSV alias: GET /entities/automatic/bulk/imports/{jobId}/failures.csv.

…/failures.csv → CSV file download (Content-Type: text/csv)
…/failures → JSON body (Content-Type: application/json)

Overview

Batch imports expose failures at three layers:

Layer	When	Where to read
Pre-job	Request rejected before `jobId` is returned (`400`)	HTTP response body (`error.code`)
Job-level	Whole job aborted (`status: failed`)	Unified history → `workerError`, `metadata.apiError`; JSON failures → `jobFailure`
Row-level	Some rows failed (`failed > 0`, job may still be `completed`)	Failures CSV/JSON per kind

Row-level failures always include a stable code (machine-readable) and message (human detail). Legacy jobs may only have free-text error; the API normalizes them on read.

Entity Row Outcomes (Created / Skipped / Failed)

Outcome	In `failures.csv`?	Where
`created`	No	Job `succeeded`
`skipped_existing`	No — not a failure	Job `skipped` / `skippedExisting`, full report CSV, JSON `skips[]`
`failed`	Yes	`failures.csv`, JSON `failures[]`

Duplicate `taxId` (Entities)

Bulk manual default uses duplicateTaxIdPolicy: skip_existing:

Same taxId + same type already in org → skipped_existing, skip code SKIPPED_DUPLICATE_TAX_ID
Does not appear in failures.csv

Bulk automatic: existing main entity → skipped_existing

refresh: false (default when omitted): SKIPPED_ENTITY_ALREADY_EXISTS — no re-enrichment
refresh: true: SKIPPED_ENTITY_ALREADY_EXISTS_REFRESHED — creation skipped, re-enrichment ran

Hard failures:

Situation	Failure code
Same taxId, different type (person vs company)	`TAX_ID_TYPE_MISMATCH`
Same taxId + type with error policy (unit API; not bulk default)	`DUPLICATE_TAX_ID`
Duplicate `externalId`	`DUPLICATE_EXTERNAL_ID`

Row-level failure codes (`BATCH_IMPORT_ITEM_FAILURE_CODES`)

Code	Meaning
`VALIDATION_ERROR`	Row failed Zod / schema validation before persistence.
`PROCESSING_ERROR`	Unexpected error while processing the row.
`ENTITY_NOT_FOUND`	Referenced entity does not exist in the organization.
`INVALID_RISK_MATRIX`	Risk matrix id invalid or not in org.
`CREATION_CONTRACT_QUOTA_EXCEEDED`	Organization contract creation quota exceeded.
`CREATION_QUOTA_EXCEEDED`	Deprecated alias of `CREATION_CONTRACT_QUOTA_EXCEEDED` (historical `failures.csv` only).
`DATABASE_INSERT_ERROR`	Database rejected insert (unclassified).
`DUPLICATE_EXTERNAL_ID`	Entity or transaction with same `externalId` already exists.
`DUPLICATE_TAX_ID`	Same taxId + type already exists (hard error path).
`TAX_ID_TYPE_MISMATCH`	taxId registered under a different entity type.
`CONSTRAINT_VIOLATION`	Other DB constraint (FK, check, unique index).
`MISSING_COUNTRY`	Entity row missing valid ISO2 country.
`INVALID_COUNTRY`	Country not allowed for import mode (e.g. automatic ≠ AR/BR/CL).
`ENRICHMENT_FAILED`	Enrichment provider failed for entity row.
`CREATION_FAILED`	Entity could not be created for the row.

Skip reason codes (`BATCH_IMPORT_SKIP_REASON_CODES`)

Not failures — used when outcome=skipped_existing:

Code	Meaning
`SKIPPED_DUPLICATE_TAX_ID`	Manual bulk skipped row: duplicate taxId + type
`SKIPPED_ENTITY_ALREADY_EXISTS`	Automatic bulk: entity already existed, refresh off
`SKIPPED_ENTITY_ALREADY_EXISTS_REFRESHED`	Automatic bulk: entity already existed, refresh on — re-enrichment ran

Risk matrix / business rules: rule execution runs after the row is created. Rule outcomes do not appear in failures.csv / JSON failures[] and do not roll back the row. Use alerts, risk score, and audit timelines for rule results.

Job-level codes (`BATCH_IMPORT_JOB_FAILURE_CODES`)

Code	Meaning
`INVALID_ENTITY_REFERENCES`	Transaction batch: `validateExistingEntity=true` and unresolved origin/destination refs — no rows created.
`TOO_MANY_ITEMS`	File exceeds plan row limit.
`CSV_PARSE_ERROR`	CSV could not be parsed or mapped.
`MAPPING_VALIDATION_ERROR`	Saved mapping or validate-csv preflight failed.
`MISSING_REQUIRED_FIELD`	Required multipart / row field missing before queue.
`COOPERATIVE_CANCEL`	Job cancelled while processing.
`WORKER_ERROR`	Unhandled worker error.

Scenario Matrix (Client FAQ)

Scenario	In row `failures`?	Typical code / location
Missing CSV column (pre-parse)	No	`400` before job
Invalid entity ref (txn batch, default validation)	No	Job `INVALID_ENTITY_REFERENCES`
Duplicate txn `externalId` with `skipDuplicates=true`	No	Counted as `skipped`
Duplicate entity `externalId` (manual import)	Yes	`DUPLICATE_EXTERNAL_ID`
Duplicate entity `taxId` (same type, bulk default)	No	`skipped_existing` → `SKIPPED_DUPLICATE_TAX_ID` in `skips[]`
Duplicate entity `taxId` (type mismatch)	Yes	`TAX_ID_TYPE_MISMATCH`
Enrichment failure (entity automatic)	Yes	`ENRICHMENT_FAILED`
User event invalid field	Yes	`VALIDATION_ERROR`
Rules / matrix evaluation error	No	Row still created

Reproducible Test Scenarios

User events (simplest row failures): valid CSV + mapping; one row with empty required field → GET …/user-event-jobs/{jobId}/failures. Entities (manual): create entity with external_id=X, import another row with same external_id → DUPLICATE_EXTERNAL_ID. Transactions (job-level): validateExistingEntity=true + originExternalId=DOES_NOT_EXIST → job failed, jobFailure.code=INVALID_ENTITY_REFERENCES. Transactions (row-level): batchErrorHandling=continue_collect_errors + mix valid rows with DB constraint violations → row entries in failures endpoint.

Limits

Max 500 row failures persisted per transaction batch job (CSV + JSON may truncate; JSON exposes truncated + failuresTotal).

Getting Started

SDK

Use Cases

Webhooks

Workflows

Monitoring (entities)

Person

Messaging

Company

Transactions

Devices

Events

Know Your Customer (KYC)

Payment Methods

Rules

Custom lists

Risk Matrix

Alerts

Investigations

Data Ingestion

Bulk imports

Documents

Enrichment

Services

Integrations

Interactive Tutorials

Batch import failure codes

Failure Download Endpoints

Overview

Entity Row Outcomes (Created / Skipped / Failed)

Duplicate `taxId` (Entities)

Row-level failure codes (`BATCH_IMPORT_ITEM_FAILURE_CODES`)

Skip reason codes (`BATCH_IMPORT_SKIP_REASON_CODES`)

Job-level codes (`BATCH_IMPORT_JOB_FAILURE_CODES`)

Scenario Matrix (Client FAQ)

Reproducible Test Scenarios

Limits

​Failure Download Endpoints

​Overview

​Entity Row Outcomes (Created / Skipped / Failed)

​Duplicate taxId (Entities)

​Row-level failure codes (BATCH_IMPORT_ITEM_FAILURE_CODES)

​Skip reason codes (BATCH_IMPORT_SKIP_REASON_CODES)

​Job-level codes (BATCH_IMPORT_JOB_FAILURE_CODES)

​Scenario Matrix (Client FAQ)

​Reproducible Test Scenarios

​Limits

Failure Download Endpoints

Overview

Entity Row Outcomes (Created / Skipped / Failed)

Duplicate `taxId` (Entities)

Row-level failure codes (`BATCH_IMPORT_ITEM_FAILURE_CODES`)

Skip reason codes (`BATCH_IMPORT_SKIP_REASON_CODES`)

Job-level codes (`BATCH_IMPORT_JOB_FAILURE_CODES`)

Scenario Matrix (Client FAQ)

Reproducible Test Scenarios

Limits