Message Batches results come back in a different order than the requests were submitted

Answers are attached to the wrong input rows

Verified 2026-10-15 · Confirmed by 0 builders · Trust 50/100

Cause

Batch results can be returned in any order, not in submission order, so pairing results with inputs by position mislabels them.

Fix

Give every request a unique custom_id (1 to 64 letters, digits, hyphens, or underscores) and join results on it. Handle each result type: succeeded, errored, canceled, expired.

Apply

const byId = new Map(inputs.map(i => [i.custom_id, i]));
for await (const r of await client.messages.batches.results(batchId)) {
  const input = byId.get(r.custom_id);
  if (r.result.type !== 'succeeded') { console.warn(r.custom_id, r.result.type); continue; }
}

Affects: Message Batches API, all models, as of 2026-10

Sources

https://platform.claude.com/docs/en/build-with-claude/batch-processing

Have your agent know this before it fails

claude mcp add --transport http footgun https://getfootgun.com/api/mcp