Claude Message Batches: What to Do With Each Result State
The Message Batches API processes independent Messages API requests asynchronously. Submitting a batch is easy. The design work is in what happens after the results come back, especially when some succeed and some do not
The Message Batches API processes independent Messages API requests asynchronously. Submitting a batch is easy. The design work is in what happens after the results come back, especially when some succeed and some do not.
When a batch fits
Use a batch for independent work that can wait: evaluations, document classification, data analysis. Use an interactive request when a person or service needs the answer before it can continue. A batch can take up to 24 hours, so check the current limits in the documentation before building anything time sensitive.
Join by custom_id, never by position
Results can come back in a different order from the requests you sent. Give each request a custom_id taken from your own record, such as ticket_8831, and store the mapping before you submit. When results arrive, write each outcome next to its source record, with the prompt version, submission time and status.
Four result states, four next steps
| State | What it means | Next step |
|---|---|---|
succeeded |
The model returned a message | Validate the message and its business meaning before any action |
errored |
The request failed | Read the error. Fix invalid input; retry only errors that are eligible |
canceled |
The batch was canceled | Check each request. A canceled batch can still contain completed results |
expired |
The request was not sent before the batch expired | Decide which requests are still useful, then resubmit those |
succeeded is the state people misread. It means a message exists, not that the message is right for the decision.
Never rerun the whole file
When a few records fail, the tempting fix is to resubmit everything. That can create duplicate tasks or overwrite decisions a person already made. Instead:
- Keep successful and unresolved records separate.
- Retry only eligible records, with their original IDs.
- Preserve completed outcomes and human decisions.
Keep the model away from the action
For refunds, notices, account changes or payments, separate the model's output from execution:
- Mark a record
approved_for_actiononly after validation and any required review. - Let the action service enforce an idempotency key, so a retry cannot run the action twice.
custom_id joins a result to its input. It does not make execution idempotent. That job belongs to the service that performs the action.
Checklist
- Requests are independent, can wait, and carry unique
custom_idvalues. - Inputs, prompt versions and results are kept and joined by ID.
- A successful message and an approved business decision are different fields.
- Partial failures have an owner and a retry rule.
- Retries cannot duplicate an external action.
Go further
- The full article, with a supplier classification example: Claude Batch API on Timo Labs.
- The exam view: task statement 4.5: Message Batches API in the CCAR-F study guide.
- Free CCAR-F practice questions test when to batch and how to handle partial failures.
Originally published by Dev.to AI. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.