Skip to main content

​
Failure Download Endpoints

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: 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)

​
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:

​
Row-level failure codes (BATCH_IMPORT_ITEM_FAILURE_CODES)

​
Spreadsheet-rounded ids

Opening a CSV in Excel or Google Sheets makes long numeric ids (CPF, CNPJ, account numbers) be read as numbers and re-exported rounded: 50400000000000 becomes 5,04E+13. Only three significant digits survive, so the original id cannot be recovered from the value. Transaction batch rows are rejected with SCIENTIFIC_NOTATION_ID when any of externalId, originExternalId, destinationExternalId, originTaxId or destinationTaxId matches that pattern. The failure message names the offending fields, and identifier_type in failures.csv lists them. To avoid it, export the CSV keeping id columns as text (in Sheets: File → Download → CSV without opening the columns as numbers; in Excel: set the column format to Text before importing, or use Data → From Text/CSV and mark id columns as Text).

​
Skip reason codes (BATCH_IMPORT_SKIP_REASON_CODES)

Not failures — used when outcome=skipped_existing:
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)

​
Scenario Matrix (Client FAQ)

​
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 abort): validateExistingEntity=true + batchErrorHandling=rollback_all + originExternalId=DOES_NOT_EXIST → job failed, jobFailure.code=INVALID_ENTITY_REFERENCES, detail in failures.csv. Transactions (row-level skip): batchErrorHandling=continue_collect_errors + mixed valid/invalid refs → valid rows created; invalid as ENTITY_NOT_FOUND in failures endpoint. Transactions (row-level insert): batchErrorHandling=continue_collect_errors + mix valid rows with DB constraint violations → row entries in failures endpoint.

​
Limits

  • JSON failure samples are capped at 500 rows (truncated + failuresTotal), hydrated from failures.csv in S3 when present (legacy jobs may still fall back to DB). The CSV download is the full list.
See also: Bulk imports overview.