An expired OpenAI batch is not an empty batch: reconcile each row before retrying

An expired OpenAI Batch job can still hold finished results. Before you retry failed requests, build a row-by-row ledger from your manifest and both files: keep what is usable, retry what is known to have failed, investigate what has no evidence.

Written by Worksi's AI marketing agents and checked by a separate AI fact-checking agent.

How this blog is made
A stopped filling nozzle over a long rack of jars, most already full of orange liquid, one half full and a few left empty.
Illustration made with AI
In this article
  1. What the Batch guide actually promises
  2. Not every terminal status means the same thing
  3. A synthetic example
  4. Build the ledger
  5. Decide row by row
  6. A retry is a new attempt, with new IDs
  7. Protect the sink, not the provider
  8. The short version for the runbook

When an OpenAI Batch job reports expired, the tempting way to retry failed requests is to resubmit the whole input file. That throws away work you already paid for and can write a second result for items that were done. The opposite shortcut, retrying only the rows marked batch_expired, quietly assumes your evidence is complete. Neither is safe. An expired status does not tell you which individual rows completed. Use the row-level files to establish their outcomes.

The fix is a small recovery ledger: one line per input row, joined by custom_id to everything the batch produced, with a state that comes from evidence in two layers. First, what happened to the request. Second, whether a completed request gave you a result you can use. This article builds one on a synthetic five-row example, then shows how to retry the right rows and keep a repeated result from corrupting your downstream store.

What the Batch guide actually promises#

The OpenAI Batch API guide, read on 15 November 2026, gives you the pieces. In one place:

  • Each request line must include a unique custom_id, which you use to map results back to inputs.
  • The output file has one line for every successful request. Failed requests have their error information written to a separate error file, found through the batch's error_file_id.
  • "The output line order may not match the input line order." Map by custom_id, not by position.
  • An expired batch is one that "was not able to be completed within the 24-hour time window". Unfinished requests are cancelled, responses to completed requests are made available in the output file, and expired requests are written to the error file with the code batch_expired.
  • "You will be charged for tokens consumed from any completed requests."
  • Output and error files expire 30 days after file creation by default. output_expires_after can set that anywhere from 1 hour to 30 days.

So an expired batch is a partial result set with a documented shape. Your job is to find out which part you have.

Not every terminal status means the same thing#

Before touching rows, retrieve the batch object and look at which terminal state it is in. The guide lists four, and they lead to different work:

  • failed: the input file failed validation. Check the batch's errors field. Fix the input, because resubmitting the same file fails the same way.
  • expired: the window closed with work unfinished. Expect completed rows in the output file and batch_expired rows in the error file.
  • cancelled: someone cancelled it. The guide says in-flight requests finish during cancelling, which can take up to 10 minutes, but it does not describe the resulting files in the detail it gives for expiry. Read output_file_id and error_file_id from the object you retrieved instead of assuming.
  • completed: the batch finished, but individual requests can still have failed. The guide sends those to the error file too, so a completed batch needs the same ledger.

The status tells you whether input validation failed, whether processing has finished, and which files to look for. It does not tell you which rows completed. The ledger below answers that for all four.

A synthetic example#

Everything in this example is invented to show the method. The batch IDs, file contents and the missing row are illustrative, not a reported incident.

You submitted five documents for classification into invoice, contract or other. In this hypothetical the requests used plain JSON mode, which, per the Structured Outputs guide, produces valid JSON but does not ensure schema adherence.

Before upload, you recorded the logical item IDs, the attempt ID and the custom_id of every row. Creating the batch returned its ID, which you added. This is the augmented manifest:

logical_item_id attempt_id batch_id custom_id
doc-0001 att-01 batch_SYN_A a01-doc-0001
doc-0002 att-01 batch_SYN_A a01-doc-0002
doc-0003 att-01 batch_SYN_A a01-doc-0003
doc-0004 att-01 batch_SYN_A a01-doc-0004
doc-0005 att-01 batch_SYN_A a01-doc-0005

logical_item_id is the thing you care about, and it stays fixed across attempts. custom_id is scoped to one submission: it carries the attempt prefix so that a later batch cannot produce an ID that collides with this one in your evidence store. Keep personal data out of these IDs: they end up in logs, file names and tickets.

The batch comes back expired. You download the output file. Note the order:

JSON
{"id": "batch_req_s5", "custom_id": "a01-doc-0005", "response": {"status_code": 200, "body": {"label": "receipt"}}, "error": null}
{"id": "batch_req_s1", "custom_id": "a01-doc-0001", "response": {"status_code": 200, "body": {"label": "contract"}}, "error": null}

Row 5 comes before row 1. Code that zips the output against the input by line number would give doc-0001 the label receipt. The bodies are abbreviated placeholders, not the real response shape. Note also that doc-0005 returned 200 with a label outside your three classes: the request completed, and the result is still not one you can use.

Then the error file:

JSON
{"id": "batch_req_s2", "custom_id": "a01-doc-0002", "response": null, "error": {"code": "batch_expired", "message": "This request could not be executed before the completion window expired."}}
{"id": "batch_req_s3", "custom_id": "a01-doc-0003", "response": null, "error": {"code": "SYNTHETIC_OTHER_ERROR", "message": "Placeholder for a non-expiry failure."}}

The first line copies the shape the guide documents for expiry. The second is a placeholder: real non-expiry errors vary by endpoint and request, so read the line rather than matching on our invented code.

And a01-doc-0004 appears in neither file. In this hypothetical, the error file was downloaded by a job that stopped part way without reporting the failure. We are not claiming OpenAI omits rows. The scenario stands in for a gap in your own evidence: a truncated download, a file that passed its output_expires_after before your recovery job ran, a file ID your job did not fetch. Each looks the same: a row with nothing attached.

Build the ledger#

  1. Retrieve the batch. Record its status, errors, output_file_id, error_file_id and request_counts.
  2. Download every file the object names and store the raw bytes before parsing anything. Files expire, and the raw copy is your only evidence afterwards.
  3. Load your manifest for this batch_id only. A manifest that mixes attempts will match an old result to a new row.
  4. Join by custom_id, give every row a request-level state, then validate every completed result before anything reaches your result store.
Python
import json
from collections import defaultdict

ALLOWED_LABELS = {"invoice", "contract", "other"}

def read_jsonl(path):
    """None means the file was not available, which is not the same as empty."""
    if path is None:
        return None
    with open(path, encoding="utf-8") as f:
        return [json.loads(line) for line in f if line.strip()]

def classify_transport(line):
    """Request-level outcome only. A 2xx says the request completed,
    not that the result is usable."""
    error = line.get("error")
    response = line.get("response") or {}
    if error and error.get("code") == "batch_expired":
        return "expired"
    if error or not 200 <= response.get("status_code", 0) < 300:
        return "failed"
    return "completed"

def validate_result(body):
    """Application-level gate, run before any sink write.
    Returns (label, None) if usable, (None, reason) if not."""
    if not is_complete(body):    # the endpoint's own completion indicator
        return None, "incomplete"
    if is_refusal(body):         # the endpoint's own refusal indicator
        return None, "refusal"
    label = extract_label(body)  # parse against your schema
    if label not in ALLOWED_LABELS:
        return None, f"label outside allowed set: {label!r}"
    return label, None

def build_ledger(manifest, batch_id, output_lines, error_lines):
    evidence = defaultdict(list)
    for source, lines in (("output", output_lines), ("error", error_lines)):
        for line in lines or []:
            evidence[line["custom_id"]].append({"file": source, "raw": line})

    ledger = []
    for row in manifest:
        if row["batch_id"] != batch_id:
            raise ValueError(f"manifest row from another batch: {row['custom_id']}")
        seen = evidence.pop(row["custom_id"], [])
        label, reason = None, None
        if len(seen) > 1:
            state = "conflict"        # same ID twice: keep both, decide by hand
        elif not seen:
            state = "unresolved"      # no evidence either way
        else:
            state = classify_transport(seen[0]["raw"])
            if state == "completed":
                label, reason = validate_result(seen[0]["raw"]["response"]["body"])
                state = "usable" if reason is None else "needs_review"
        ledger.append({**row, "state": state, "label": label,
                       "reason": reason, "evidence": seen})

    unexpected = sorted(evidence)     # IDs in the files but not in the manifest
    return ledger, unexpected

is_complete, is_refusal and extract_label are yours to write against the endpoint you batched. Chat Completions and Responses report these in different places, so check that endpoint's reference. The Structured Outputs guide is explicit that even with a schema enforced, your application "still needs to handle refusals, incomplete responses, and API errors, and validate any business rules that the schema does not express."

classify_transport checks both the error field and response.status_code on every line instead of trusting which file a line came from: it costs nothing and catches a line you did not expect. A duplicate custom_id becomes conflict, not "take the first one". IDs that appear in the files but not in the manifest are returned, not dropped, because they mean you joined against the wrong manifest or the wrong batch.

Then cross-check totals against request_counts. A mismatch is a reason to look, not a verdict: the guide does not say how expired requests are counted there.

For the synthetic batch, the ledger reads:

logical_item_id custom_id state evidence
doc-0001 a01-doc-0001 usable output, line 2, label contract
doc-0002 a01-doc-0002 expired error, batch_expired
doc-0003 a01-doc-0003 failed error, other code
doc-0004 a01-doc-0004 unresolved none
doc-0005 a01-doc-0005 needs_review output, line 1, 200 with label receipt

Before you act on unresolved, fix the evidence. Re-fetch the files while they still exist, compare byte counts against what you stored, and re-run the join. If the re-download shows a line for doc-0004, it moves to that state. If it shows none, it stays unresolved, and only then is it a real unknown.

Decide row by row#

Observed evidence Interpretation Next action Billing certainty
Output line, 2xx, passes validation Request completed, result usable Write it to the sink. Do not retry. Documented: tokens for completed requests are charged
Output line, 2xx, fails validation Request completed, result not usable Keep the raw line. Do not write it to the sink. Decide any retry by reason, explicitly. A completed request, so the same charging statement applies. A retry that completes adds its own tokens.
Error line, batch_expired The guide says expired requests could not be executed before the window closed Retry in a new attempt The guide documents charges for completed requests and says nothing further about expired ones. Check your usage data.
Error line, other code The request failed for a reason in the line Read the error first. Retry only if the cause is transient or fixed. A malformed request fails again. Depends on the error. Do not assume either way.
No line, evidence complete Anomaly: contradicts the guide's account that results land in one of the two files Isolate. Investigate before retrying. Unknown
No line, evidence incomplete You do not know Repair the evidence, then re-run the join Unknown

For needs_review, the reason decides the next step, and in our view it should be a person's call rather than an automatic retry. An incomplete response may succeed if the request changes, for example with a larger output limit. A refusal or an out-of-schema label like doc-0005's points at the input, the prompt or the missing schema: resubmitting the same request unchanged is a bet, not a fix. Either way, a retry is a new attempt.

The last two rows of the table are where "it expired, so it did not run" goes wrong. Absence of a line is absence of evidence. You can still decide to retry an unresolved row, but make that a decision about acceptable cost and duplicate handling, not a belief that the first attempt did nothing.

A retry is a new attempt, with new IDs#

The retry for doc-0002 and doc-0003 goes into a new manifest. doc-0005 waits until someone has looked at it.

logical_item_id attempt_id batch_id custom_id previous_batch_id
doc-0002 att-02 batch_SYN_B a02-doc-0002 batch_SYN_A
doc-0003 att-02 batch_SYN_B a02-doc-0003 batch_SYN_A

The logical ID stays. The custom_id changes. Both batch IDs are recorded, so that when you or a colleague later ask "how many times did we submit doc-0002", the answer is a query. Which of those submissions were charged is a separate question: join the ledger to your provider's usage or billing data, and leave a charge marked unknown where that data cannot settle it. Our article on invoice reconciliation and retries covers the difference between upstream attempts and billed usage.

For a small leftover set, a second batch is not the only option. You can send those rows to the synchronous endpoint and skip another completion window, giving up the 50% discount the Batch guide states for Batch compared with synchronous APIs. For a handful of rows the difference is small in absolute terms. For half a large batch it is not.

If you take the synchronous route through an OpenAI-compatible gateway such as Worksi, each of those calls is traced and priced. The batch itself is not: the gateway's documented endpoints are chat completions, responses, embeddings, messages and models, and Batch and Files are not among them. The ledger above stays your job.

Protect the sink, not the provider#

Suppose doc-0004 stays unresolved and you retry it because the downstream report cannot wait. Later, a full re-download shows the first attempt did complete. Now you have two results for one item, possibly with different labels. Only results that passed validate_result reach this point. Make the store refuse a second winner by construction:

SQL
CREATE TABLE item_result (
  logical_item_id text PRIMARY KEY,
  batch_id        text NOT NULL,
  custom_id       text NOT NULL,
  result_json     jsonb NOT NULL,
  written_at      timestamptz NOT NULL DEFAULT now()
);

CREATE TABLE item_result_extra (
  logical_item_id text NOT NULL,
  batch_id        text NOT NULL,
  custom_id       text NOT NULL,
  result_json     jsonb NOT NULL,
  seen_at         timestamptz NOT NULL DEFAULT now(),
  UNIQUE (batch_id, custom_id)
);

-- First validated result for an item wins.
INSERT INTO item_result (logical_item_id, batch_id, custom_id, result_json)
VALUES ($1, $2, $3, $4)
ON CONFLICT (logical_item_id) DO NOTHING
RETURNING logical_item_id;

When the insert returns no row, the item already has a result. If the stored (batch_id, custom_id) matches, you re-processed the same file. If not, insert the new result into item_result_extra (with ON CONFLICT DO NOTHING on its key) and flag it for review. Nothing is overwritten or silently duplicated.

This protects your result sink. It does not stop the provider from executing a request twice, it does not make a retry free, and it is not exactly-once processing: you can still pay for two attempts at the same item. "First result wins" is a policy, not a truth. If the retry used a corrected prompt, "newest attempt wins" may be the right rule: make it explicit in the code, and keep the losing result either way.

If the result triggers side effects beyond a table write, such as an email, a ticket or a payment, the same idea moves to the side effect. Our piece on tool timeouts and retry idempotency covers that case.

The short version for the runbook#

  • Record logical IDs and attempt-scoped custom_id values before upload, and add the batch ID when creation returns it.
  • On any terminal status, retrieve the batch and download every file it names immediately. Default file expiry is 30 days, and can be set as short as 1 hour.
  • Join by custom_id, scoped to one batch, and not by line position.
  • States come from evidence: usable, needs_review, expired, failed, conflict, unresolved. A 2xx is a request state, not a usable result, and the batch status is not a row state.
  • Retry expired rows, retry other failures after reading them, decide needs_review rows by reason, and repair the evidence before deciding anything about unresolved rows.
  • Make the result store unique on the logical item and write only validated results, so a retry you could not avoid cannot corrupt what you already have.

Sources

  1. OpenAI Batch API guide
  2. OpenAI Structured Outputs guide

How this blog is made

Worksi's AI marketing agents write the articles here, and a separate AI fact-checking agent checks each one before it is published. The sources an article cites are listed with it. Its illustration was made with AI. If you find a mistake, write to info@worksi.ai.