Your agent’s bulk import timed out. Confirm the result before retrying.

The riskiest point in an import is often a missing response. A client timeout can coexist with a server that accepted the request, created a proposal, or completed a merge. Generating a fresh batch at that moment can turn the same source material into duplicate business records.

Recovery starts with two questions: what happened to the original request, and which business objects now exist? A request idempotency key and a stable business key answer different parts of that problem.

Prepare a batch manifest before sending

The live OpenAPI caps bulk-change-request at 1,000 records. Those records are proposed in a single ChangeRequest. Split larger work into inspectable batches, or choose an appropriate dedicated import process.

Keep the target Space and Base, submitting identity, source reference or digest, business keys, exact request body, idempotency key, and returned CR ID. The manifest should make a changed payload distinguishable from the original request. Keep credentials out of it.

Structural illustration · designed workflow

Give requests and business objects different identities

The bulk-create idempotencyKey is scoped per Base and submitter. Retrying the same key in that scope returns the original CR instead of creating another one. This supports ambiguous-response recovery; it does not establish a business uniqueness constraint across the Base.

A stable business key identifies the object in the source system. Check duplicate keys in the source and existing canonical records before import. Verify the same keys afterwards. Similar names or matching display titles are weak substitutes for stable identity.

Recover the original proposal first

If a CR ID was returned, read that CR and inspect its status, operations, and resulting records. If the response was lost, recover the submission using the preserved original payload, target, and idempotency key. Do not rearrange or edit a batch and blindly reuse its old key as if it were unchanged.

ChangeRequest states matter: in_review is a proposal awaiting review; approved is not yet proof of merge; merged should be followed by a canonical read. The absence of a current record alone does not prove that the request never arrived.

Structural illustration · designed workflow

Verify each batch independently

One bulk request is one CR. Several batches should not be assumed to form a transaction across requests. Maintain a manifest state for each batch: response unknown, CR created, awaiting review, merged, or readback verified. These are suggested workflow states your agent or script must maintain.

If earlier batches passed and a later one timed out, resume the unconfirmed batch. Do not clear the table or resend the whole file with fresh keys. At the end, check that each business key resolves to exactly one record with the required field values; list missing, duplicate, and conflicting objects.

Update existing objects against their current version

Once an object exists, use an update rather than another create. Preserve recordId and read the current baseCommitId. Submit only the fields that need changing. Omitted fields in sparse updates remain unchanged, while null clears a field; missing source data should not automatically become null.

Permissions remain part of recovery. Write access may merge immediately; proposal-only access waits for review. Where a person must review, retain that boundary explicitly through the supported interface. A retry does not authorize overriding a concurrent edit or bypassing review.

Structural illustration · designed workflow

Ask the agent for a recoverable result

An adaptable instruction is:

Prepare a manifest for this Base and deduplicate stable business keys. Preserve each batch's original payload, separate idempotency key, and CR ID. After a timeout, inspect the original CR and canonical state before retrying. Pause dependent work for unconfirmed batches. After merge, read back counts and required fields by business key, and report missing, duplicate, conflicting, and remaining items.

Exercise a small representative import through submission, review, readback, and interruption recovery before expanding it. The useful deliverables are the manifest, original proposal links, and verified uniqueness—not merely a successful upload message. Use the REST API guide to confirm the connection and keep each object's identity intact across retries.