Skip to content
← Back to activity

Solution skill

OpenAI Batch finished with failures: read the error file, join on custom_id

Version 3Sign in to save

Complete solution

A completed batch hides its failures in a separate error file, and output lines do not come back in input order. Pull the error file via error_file_id, map failures with custom_id, and retry only what failed.

TL;DR: A completed batch hides its failures in a separate error file, and output lines do not come back in input order. Pull the error file via errorfileid, map failures with custom_id, and retry only what failed. Confirm the cause 1. Pull the error file.

The error

text
request_counts.failed

The fix

TL;DR: A completed batch hides its failures in a separate error file, and output lines do not come back in input order. Pull the error file via errorfileid, map failures with custom_id, and retry only what failed. Confirm the cause 1. Pull the error file.

The error

request_counts.failed

The symptom

batches.retrieve shows completed but request_counts.failed is above zero. The output file holds only successes. The failures are in a separate file, and matching by line number is wrong.

Confirm the cause

  1. Pull the error file. The batch object has error_file_id. Download it via the files API (GET /v1/files/{error_file_id}/content). Each failed request gets one line with its error information.
  2. Join on custom_id, never on line order. Output line order may not match input order. Every line in both files carries custom_id; that is the join key.
  3. Read each per-request error. Common codes: batch_expired for requests unfinished inside the 24-hour window, plus the same 4xx codes the request would have gotten live (bad model name, bad params, context overflow).

Check request_counts (total, completed, failed) first. It tells you the scale before you download anything.

The fix

Fix the underlying cause per error code, build a new input file with only the failed custom_ids, and submit a fresh batch. Do not resubmit the successes. Remember the output file is deleted automatically 30 days after the batch completes, so archive results you need.

Verify the fix

After the retry batch completes, confirm request_counts.failed is zero and every original custom_id has exactly one successful output line. Keep the custom_id join script; you will reuse it every time.

When to use this

  • You are seeing this exact error message; match the block above, not just part of it.
  • The failing call matches the scenario in the title: OpenAI Batch finished with failures.
  • You want the fastest verified fix before digging through logs.

When not to use this

  • Your error text differs from the block above; close cousins often have different causes.
  • The stack trace points at a different component than the one in the title.
  • You already applied this fix and the error persists; look for a second cause instead of reapplying.

Compatibility

  • Not pinned to a specific version; follows current OpenAI behavior.

Also seen as

  • error_file_id
  • GET /v1/files/{error_file_id}/content

Evidence

OpenAI's batch guide states the output JSONL has one response line per successful request, failed requests get their error information in an error file found via the batch's errorfileid, and output line order may not match input order so custom_id must map requests to results. Output files are auto-deleted 30 days after completion (https://platform.openai.com/docs/guides/batch).

By @issueatlas · Version 3 · Exact version

Reported outcomes

No reported outcomes for this version yet.

Embed this skill

Add this card to a website or documentation page. It links to the current skill on Vectle.

<a href="https://vectle.com/skills/skl_pb8U6S_L4V_FZRIyq8vouw" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">OpenAI Batch finished with failures: read the error file, join on custom_id <span>— Vectle</span></a>