An empty OpenAI response can consume output tokens before producing an answer
A blank Responses API answer with nonzero output usage is not one failure. A small diagnostic separates token exhaustion during reasoning from refusals, tool calls, missing evidence and your own parser, then a controlled budget test decides what to change.
Written by Worksi's AI marketing agents and checked by a separate AI fact-checking agent.
How this blog is made
In this article
Your OpenAI Responses API call came back with empty output, yet usage.output_tokens is not zero. The tempting fix is to raise max_output_tokens and retry. An empty answer is a symptom with several distinct causes, five of which this article separates: the reasoning budget ran out before any visible text, the model refused, the model returned a tool call or another item instead of text, the request never produced a response object, or the text is in the payload and your code failed to read it. A higher cap may help the first, when the context window still has room. It does nothing for the other four, and any longer generation it allows is billed.
This article gives you a small diagnostic for one non-streaming Responses API call, a decision table that maps what it records to a next step, and a change-one-variable budget test. Nothing here is undocumented: OpenAI's reasoning guide already says the budget includes reasoning and can run out before visible text. What the guide does not give you is a way to tell that case apart from the others in production logs.
What OpenAI already documents#
The reasoning guide, read on 15 November 2026, says three things that matter here:
max_output_tokenslimits the total tokens the model generates, "including reasoning tokens, visible output tokens, and non-visible formatting tokens".- If generated tokens reach the context window limit or the
max_output_tokensvalue, the response has statusincompleteandincomplete_details.reasonset tomax_output_tokens. This "might occur before any visible output tokens are produced", so you can pay for input and reasoning tokens with no visible response. - Reasoning tokens appear in
usage.output_tokens_details.reasoning_tokens, and are billed as output tokens. OpenAI recommends reserving at least 25,000 tokens for reasoning and outputs when you start experimenting, then adjusting.
Two details are easy to miss. First, max_output_tokens as the reason covers the context window limit too, so a bigger output cap does nothing if the input already fills most of the window. Second, output usage includes non-visible formatting tokens, so output_tokens minus reasoning_tokens is not a count of visible text.
A developer forum report from 7 February 2026 shows what this looks like on the wire. With gpt-5.2-codex and max_output_tokens=400, the reporter got status: "incomplete", reason max_output_tokens, an output array holding only reasoning items, no message item, an empty output_text and nonzero usage.output_tokens. In their small trials (5 runs per setting) the blank rate rose with reasoning effort. That is one person's reproduction on one model, not a measured rate, but it is the exact shape the diagnostic below looks for.
Record the response shape before you change anything#
The SDK's output_text property is convenient, and it is the wrong thing to log. It is empty for an exhausted budget, for a refusal and for a pure tool call alike. The output array is what tells them apart, and the Response type in the Python SDK says its length and order depend on the model's response, so do not assume the first item is a message.
Record these, per call:
- Response id, the
modelthe response reports, themax_output_tokensyou requested and the reasoning effort you sent. status. The SDK listscompleted,failed,in_progress,cancelled,queuedandincomplete(ResponseStatus).incomplete_details.reason. The SDK listsmax_output_tokens,max_messages,content_filterandsteered, and allows the reason to be absent.- Whether
outputwas present at all, the types of its items, and inside eachmessageitem its content part types and itsphase. A message's content parts areoutput_textorrefusal, andphase, when set, labels the messagecommentaryorfinal_answer(ResponseOutputMessage). - Visible text length in characters, not the text itself.
usage.output_tokensandusage.output_tokens_details.reasoning_tokenswhen present (ResponseUsage).- For an exception instead of a response: its type, and output usage marked unknown.
Do not log the prompt, the output text or the API key by default. Shape and counts support a hypothesis when the fields it needs are present. When they are missing, the record says so instead of guessing.
Switch off hidden retries for a controlled test. The Python SDK retries some connection and API failures twice by default (DEFAULT_MAX_RETRIES = 2), inside one responses.create call, out of sight of your record. With max_retries=0, one call is one request.
Here is a synthetic, no-tool version in Python against the official openai package. Every field is read defensively, and a missing value stays None rather than becoming zero.
import time
import openai
from openai import OpenAI
# max_retries=0: no hidden SDK retries inside one call. The key comes from
# OPENAI_API_KEY in the environment; never log it.
client = OpenAI(max_retries=0)
def diagnose(d, requested_max_output_tokens, requested_effort):
"""Record one non-streaming Responses API result by shape and counts only."""
d = d or {}
raw_output = d.get("output")
output = raw_output if isinstance(raw_output, list) else []
item_types, part_types, phases = [], [], []
visible_chars, refusal_present = 0, False
for item in output:
if not isinstance(item, dict):
continue
item_types.append(item.get("type"))
if item.get("type") != "message":
continue
phases.append(item.get("phase")) # None = not set by this model
for part in item.get("content") or []:
if not isinstance(part, dict):
continue
ptype = part.get("type")
part_types.append(ptype)
if ptype == "output_text":
visible_chars += len(part.get("text") or "")
elif ptype == "refusal":
refusal_present = True
usage = d.get("usage") or {}
details = usage.get("output_tokens_details") or {}
return {
"response_id": d.get("id"),
"model": d.get("model"),
"requested_max_output_tokens": requested_max_output_tokens,
"requested_effort": requested_effort,
"status": d.get("status"), # None = not reported
"incomplete_reason": (d.get("incomplete_details") or {}).get("reason"),
"error_present": d.get("error") is not None,
"output_present": isinstance(raw_output, list),
"output_item_types": item_types,
"message_part_types": part_types,
"message_phases": phases,
"visible_text_chars": visible_chars,
"refusal_present": refusal_present,
"output_tokens": usage.get("output_tokens"), # None = not reported
"reasoning_tokens": details.get("reasoning_tokens"), # None = not reported, not zero
}
MAX_OUT = 400 # deliberately small for a test account
EFFORT = "medium" # only a value YOUR_MODEL supports
started = time.monotonic()
try:
resp = client.responses.create(
model="YOUR_MODEL",
reasoning={"effort": EFFORT},
input="Synthetic test prompt. No tools, no customer data.",
max_output_tokens=MAX_OUT,
)
record = diagnose(resp.model_dump(), MAX_OUT, EFFORT)
except openai.APIStatusError as e:
record = {"api_error_status": e.status_code, "output_tokens": None}
except openai.APIConnectionError as e:
record = {"transport_error": type(e).__name__, "output_tokens": None}
record["latency_s"] = round(time.monotonic() - started, 2)
print(record)
Replace YOUR_MODEL with the model and snapshot you run in production, and keep it fixed while you test. Supported reasoning effort values vary by model, so check the model's page before you pick one.
Map what you recorded to one next step#
Empty text alone identifies nothing. The combination of fields can support a hypothesis, and some combinations support none.
| What the record shows | What it supports | Next step |
|---|---|---|
incomplete, reason max_output_tokens, a nonempty output of only reasoning items, 0 visible chars, output_tokens reported and > 0 |
Budget or context ran out before visible text, as the reasoning guide documents | Run the budget test below. Check input size against the model's context window first. |
incomplete, reason max_output_tokens, visible chars > 0 |
Some text was emitted before generation became incomplete | Check phase. Show it only as a labeled partial answer, and only if it is user-facing answer content, not commentary. Never parse it as a finished structured result. |
incomplete, reason content_filter, max_messages or steered |
A documented reason other than the budget | Raising max_output_tokens is not indicated. Handle that reason on its own terms. |
incomplete, no reason |
Insufficient evidence | Do not rule the budget in or out. Keep the record and its usage, and look at the other fields. |
completed, message with a refusal part |
Refusal | Handle as a refusal. Do not treat a larger budget as a remedy for it. |
completed, no visible text, a function call item |
A tool handoff | Continue a valid handoff through your tool executor. Treat it as a bug only if your client failed to handle the call. |
completed, no visible text, another non-message item or an empty output |
An item type or shape your code did not expect | Inspect and handle the actual item type. Investigate unsupported or unexpected output separately. completed does not guarantee a text answer. |
A returned response with status failed or error present |
The provider reported a failure | Read the error. Keep any usage the response carries; mark only absent counts unknown. |
| An exception: API status error, connection error or timeout, no response object | No response-level usage evidence | Usage may be unavailable from the call. Reconcile it separately against your provider's usage records. A timeout leaves the outcome unknown. |
queued or in_progress |
Not finished (background responses) | Wait for a terminal status before you classify anything. |
Raw record shows output_text with chars > 0, but the user saw nothing |
Your parser or rendering | Fix the client. Do not retry the model. |
| Status missing, or any shape not listed above | Unclassified | Insufficient evidence. Count these separately instead of folding them into a row. |
Three things the table deliberately does not assume. A completed response does not always contain an answer. A missing reasoning_tokens field does not mean the model did no reasoning. And reported output minus visible text is not all reasoning, because formatting tokens count too.
Test the budget one variable at a time#
In our view, the production cap should come from the output_tokens you observed on completed runs of your prompt, plus a margin you choose, reviewed when the prompt or model changes. That ties the cap to measured behavior of your workload rather than to a vendor's starting point. OpenAI's 25,000-token reservation is a starting point for experiments, not a minimum every call needs.
If the first row of the table is what you see, get those observations in a test project, not by raising the production cap and watching.
- Fix the model and snapshot, the prompt (synthetic or redacted), the reasoning effort,
store, and use no tools. Keepmax_retries=0. - Check the model page for its context window and maximum output. Input tokens plus the output budget must fit, or you are testing the window, not the cap.
- Change only
max_output_tokens, in steps. Run several requests at each step: the forum report used only 5 runs per setting, so a single run per step tells you little. - Record the diagnostic for every run, plus latency and a quality check against what a correct answer must contain.
- If you want to know about reasoning effort, run it as a separate experiment with the budget fixed, and only with values the model supports.
What you get is evidence for that prompt and model, not a guarantee. A budget that completes every run today can still end incomplete on a longer input or a harder question. The cap is an upper bound on generated tokens, not a charge: you pay for what the model generates. A higher cap may help confirmed output-cap exhaustion when the context window has room, and it may add cost and latency when a generation uses the extra tokens. It does not make the answer correct, and it does not address parser, refusal or tool-handling causes.
Retry is your design, with a ceiling#
OpenAI does not promise that a retry with a bigger budget will complete. A retry is an application choice, and it should be narrow:
- Retry only the first row of the table, with every field it requires present.
- Cap attempts and total tokens per user request, and count every attempt's reported usage separately, keyed by response id. The incomplete attempt was billed; the guide says so.
- Record exceptions as attempts with unknown usage, and stop rather than retry blind.
def budget_exhausted_before_text(rec):
"""True only for the first row of the table, with every field present."""
types = rec.get("output_item_types") or []
out = rec.get("output_tokens")
return (rec.get("status") == "incomplete"
and rec.get("incomplete_reason") == "max_output_tokens"
and rec.get("output_present") is True
and len(types) > 0
and all(t == "reasoning" for t in types)
and rec.get("visible_text_chars") == 0
and out is not None and out > 0)
budgets = [4000, 16000] # illustrative; take yours from the budget test
attempts = []
for budget in budgets: # caps application-level generation attempts
try:
resp = client.responses.create( # client has max_retries=0
model="YOUR_MODEL",
reasoning={"effort": EFFORT},
input="Synthetic test prompt. No tools, no customer data.",
max_output_tokens=budget,
)
except openai.APIError as e:
attempts.append({"requested_max_output_tokens": budget,
"exception": type(e).__name__,
"output_tokens": None}) # unknown; reconcile separately
break
rec = diagnose(resp.model_dump(), budget, EFFORT)
attempts.append(rec)
if not budget_exhausted_before_text(rec):
break
reported = [a.get("output_tokens") for a in attempts]
total_output_tokens = sum(t for t in reported if t is not None)
usage_unknown = any(t is None for t in reported) # say so, do not count it as 0
The list caps the generation attempts your application makes. It is not a ceiling on downstream requests if a gateway or proxy between you and the provider retries on its own. Count that layer separately.
With tools the rule changes. A response that stopped part-way may already have produced function calls that your code executed. Repeating the request can repeat the side effect. Reconcile what ran before you retry, the same way as for a tool call that timed out.
Structured output needs its own line. The Structured Outputs guide says the schema constraint applies to completed, non-refusal output, and that your application still has to handle refusals, incomplete responses and API errors, and validate business rules the schema does not express. Partial JSON from an incomplete response is not a result. Do not repair it and pass it on.
Streaming is a different evidence problem#
This diagnostic covers non-streaming calls. In a stream, a connection that drops before the final event leaves no terminal status at all: missing evidence, not a documented incomplete response. See streaming fallback after the first token and missing streaming usage after cancellation.
Where the per-attempt record lives#
The diagnostic belongs in your application, because only your code knows what it requested and what it showed the user. If your calls go through Worksi, the gateway serves /v1/responses where the provider does and records every Responses call as a span with model, tokens, cost and status, so each attempt in a retry shows up as its own priced call. The gateway also has its own retry layer, up to two retries and then your fallback models, so count it when you set an attempt ceiling. Use the application record to interpret the settings you requested and what your user saw.
What this leaves unknown#
When the fields it needs are present, the record supports one hypothesis. It does not tell you how often each case occurs until you count your own records, including the unclassified ones, why the model needed so much reasoning on a given prompt, or whether the answer you finally got is right. Count the rows over a week before you decide that budget is your problem.
Sources
- OpenAI: Reasoning models guide
- OpenAI: Structured model outputs guide
- OpenAI Developer Community: Responses API empty output_text when status=incomplete due to max_output_tokens
- openai-python: Response type
- openai-python: ResponseOutputMessage type
- openai-python: ResponseStatus type
- openai-python: ResponseUsage type
- openai-python: client constants (DEFAULT_MAX_RETRIES)
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.