Batch Failure Recovery with custom_id and Sample-First Prompt Refinement

1.custom_id: the only link between a request and its result

Each entry in a batch has two parts: a custom_id you choose and a params object holding normal Messages API parameters. The custom_id must be unique within the batch, 1 to 64 characters long, and use only letters, digits, hyphens, and underscores. It matters because results don't come back in the order you submitted them. The results file is JSONL, one line per request, and the custom_id is the only reliable way to match a line to the document it came from.

message_batch = client.messages.batches.create(
    requests=[
        Request(
             ? ="my-first-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-5-5",
                max_tokens=1024,
                messages=[
                    {
                        "role": "user",
                        "content": "Hello, world",
                    }
                ],
            ),
        ),

Pick custom_id values that point straight back to your own records, such as an invoice number or document key. Generic values like request-1 tell you nothing on their own. The docs specifically recommend meaningful custom_id values because the order of results isn't guaranteed. When a result fails, its custom_id tells you exactly which source document to resend, with no extra lookup table needed.

Sources12

2.Reading results: four outcomes, and only one is billed

You poll the batch until its processing_status changes from in_progress to ended. At that point, each request has exactly one of four result types. Only succeeded requests are billed. The request_counts field on the batch shows how many requests landed in each state, so you can see the size of the cleanup job before reading a single line. Because the results file can be large, the docs recommend streaming it rather than downloading it all at once.

for result in client.messages.batches.results(
    "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d",
):
    outcome = result.result
    match outcome.type:
        case "succeeded":
            print(f"Success! {result.custom_id}")
        case "errored":
            if outcome.error.error.type == "invalid_request_error":
                # Request body must be fixed before re-sending request
                print(f"Validation error {result.custom_id}")
            else:
                # Request can be retried directly
                print(f"Server error {result.custom_id}")
        case "expired":
            print(f"Request expired {result.custom_id}")

Sources1

3.Resubmitting only what failed, with the right fix

A request that fails doesn't affect any other request in the same batch. That makes recovery targeted. You don't rerun the whole batch and pay again for thousands of results you already have. Instead, collect the custom_ids of the failed requests and put only those into a new batch. A batch can't be edited after submission, so a new batch is the only way to resend anything.

How you fix each failure depends on its type. An invalid_request_error means the request itself is wrong and has to be changed before you resend it. Server errors and expired requests can go back unchanged. The most common invalid-request case in document pipelines is an input that is too big. If a document on its own exceeds the model's context window, the API rejects it with a 400 invalid_request_error that says the prompt is too long. Resending it unchanged will fail again. You need to split that document into chunks that fit, each with its own custom_id derived from the parent's. You can use the token counting API to check sizes before resubmitting.

Sources13

4.Refine on a sample before you batch the full volume

Every failed or unusable result costs you another submission cycle, and on a batch that can mean up to a day of extra latency, which also eats into your SLA. The cheapest failure is one you catch before the large run starts. The batch docs suggest dry-running a single request shape against the synchronous Messages API to catch validation errors. That fast test confirms the request is well formed before you send thousands of copies of it.

Output quality needs the same treatment. In Anthropic's account of building its multi-agent research system, the team says to start evaluating right away on small samples. Early prompt changes can have large effects, for example raising success from 30% to 80%, so even about 20 representative cases make those effects visible. For batch work this means running the prompt on a small, varied sample of real documents. Use synchronous calls so you can iterate quickly. Fix the prompt until the sample passes, and only then submit the full volume, when the first-pass success rate is already high.

Sources14

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.Batch results come back in the order the requests were submitted, so you can match them by position.Why is that wrong?

   Order isn't guaranteed. Each result line carries the custom_id you assigned, and that is the only reliable join key.

   Covered in custom_id: the only link between a request and its result

2. 2.When some requests in a batch fail, the safest fix is to resubmit the whole batch, or to edit the failed entries in place.Why is that wrong?

   Failures are isolated to individual requests, and a submitted batch can't be modified. Put only the failed custom_ids into a new batch, and change the ones that failed with invalid_request_error first.

   Covered in Resubmitting only what failed, with the right fix

Practise it for real

Run a two-request batch end to end and handle its results by custom_id

1. 1.Create a batch with client.messages.batches.create, passing two Request entries with custom_ids my-first-request and my-second-request

   Why: Each entry needs a unique custom_id plus standard Messages params

   You should see: A message_batch object whose processing_status is in_progress

2. 2.Poll with client.messages.batches.retrieve(batch_id) every 60 seconds until processing_status equals ended

   Why: Results are only available after processing ends

   You should see: request_counts showing how many requests succeeded, errored, were canceled, or expired

3. 3.Stream client.messages.batches.results(batch_id) and branch on result.result.type, printing result.custom_id

   Why: Results may arrive in any order, so custom_id is the join key

   You should see: One line per request, possibly not in submission order

4. 4.Collect any custom_ids that did not succeed into a list for a follow-up batch

   Why: Only failed requests need resubmitting, and invalid_request_error ones need their body fixed first

   You should see: An empty list on a clean run, or only the failed custom_ids otherwise