Transaction batch failures

curl --request GET \
  --url http://api.gu1.ai/batch-import/transaction-jobs/{jobId}/failures \
  --header 'Authorization: Bearer <token>'

{
  "success": true,
  "jobId": "<string>",
  "kind": "<string>",
  "status": "<string>",
  "failures": [
    {}
  ],
  "jobFailure": {},
  "truncated": true,
  "failuresTotal": 123
}

GET

batch-import

transaction-jobs

{jobId}

failures

Transaction batch failures

curl --request GET \
  --url http://api.gu1.ai/batch-import/transaction-jobs/{jobId}/failures \
  --header 'Authorization: Bearer <token>'

{
  "success": true,
  "jobId": "<string>",
  "kind": "<string>",
  "status": "<string>",
  "failures": [
    {}
  ],
  "jobFailure": {},
  "truncated": true,
  "failuresTotal": 123
}

Endpoints

GET https://api.gu1.ai/batch-import/transaction-jobs/{jobId}/failures.csv
GET https://api.gu1.ai/batch-import/transaction-jobs/{jobId}/failures

…/failures.csv → CSV file download (Content-Disposition: attachment)
…/failures → JSON body

Authentication

Authorization: Bearer YOUR_API_KEY

Requires at least one of: transactions:create, entities:bulk_import, events:create.

HTTP responses

Status	When
`200`	Job found (CSV download or JSON body)
`401`	Not authenticated
`403`	Missing batch-import permission
`404`	Unknown `jobId` or job belongs to another organization

CSV columns

Column	Description
`external_id`	Transaction `externalId`
`code`	Stable failure code — catalog
`error`	Human-readable message (same as `message` in JSON)

Legacy CSV rows (no code column) are normalized on download when possible.

JSON response

success

boolean

Always true when job exists.

jobId

string

Batch job id.

kind

string

transaction_batch

status

string

queued | running | completed | failed | …

failures

array

Row failures: { externalId, code, message }. Empty when all rows succeeded or job failed entirely before per-row collection.

jobFailure

object

Present when status=failed for whole-batch errors (e.g. INVALID_ENTITY_REFERENCES): { code, message, details? }.

truncated

boolean

true when more than 500 failures exist.

failuresTotal

number

Total failed rows stored for the job.

{
  "success": true,
  "jobId": "abc-123",
  "kind": "transaction_batch",
  "status": "completed",
  "totalItems": 10,
  "succeeded": 9,
  "failed": 1,
  "skipped": 0,
  "failures": [
    {
      "externalId": "txn-009",
      "code": "CONSTRAINT_VIOLATION",
      "message": "…"
    }
  ],
  "truncated": false,
  "failuresTotal": 1
}

Default batchErrorHandling=rollback_all aborts the batch on first insert error — often no row-level failures are stored. Use continue_collect_errors or stop_keep_success to populate this endpoint. Entity reference errors with validateExistingEntity=true fail the whole job (jobFailure), not individual CSV rows.

Batch import failure codes User-event batch failures

⌘I

​Endpoints

​Authentication

​HTTP responses

​CSV columns

​JSON response

Endpoints

Authentication

HTTP responses

CSV columns

JSON response