OpenAI Incomplete Response Reasons Need an Explicit Application Policy
OpenAI Responses can finish with an incomplete status and a reason such as an output-token limit, message limit, content filter, or WebSocket steering. Production clients need a reason-specific policy before they display text, continue a workflow, retry a request, or accept tool output. This guide defines that policy, its audit record, and the boundary between routed HTTP enforcement and application-owned recovery.

An OpenAI Response can finish with status: incomplete and still contain output items. The response object then carries incomplete_details, including a reason that explains the stop condition. A client that reads only output_text can treat a clipped answer as finished, hand partial structured data to another component, or continue an agent loop with missing context. I want the completion check ahead of every consumer. The response status and reason should decide display, retry, continuation, and audit behavior before any output becomes operational.
TL;DR
- Check the top-level Response status before displaying text, parsing business data, or continuing an agent loop.
- Give each documented incomplete reason its own policy; token limits, message limits, content filtering, and WebSocket steering require different handling.
- Treat unknown reasons as a schema-change event with a closed operational outcome and an alert.
- Keep retries and continuation under application ownership, with one record for the original response and every successor.
Incomplete is a terminal outcome with usable metadata
OpenAI's Create a response reference defines six top-level response states: completed, failed, in_progress, cancelled, queued, and incomplete. It separately defines incomplete_details for a response that ended early. As of November 21, 2026, the documented reason values are max_output_tokens, max_messages, content_filter, and steered.
That separation matters in client code. Transport success says the API returned a response object. The response status says what happened during generation. Output presence says only that the object contains material. A production acceptance decision needs all three layers in that order.
I would reject any release that uses non-empty output as its completion test. A paragraph ending halfway through a sentence is the visible failure. Partial JSON that still parses is worse because it can look complete on a dashboard.
The first branch should classify the top-level status. A completed response proceeds to item validation, while an incomplete response enters the reason policy. The other states follow their own queue, cancellation, or failure handling. An absent reason on an incomplete response belongs in the unknown branch.
Each reason needs a separate recovery rule
The reason is a policy input. A user-facing message should follow only after the route maps that input to an application outcome. Define permitted actions by application route and data class.
max_output_tokensmeans generation reached the configured output ceiling. Preserve the partial output for diagnostics, mark it operationally unaccepted, and let the application decide if a bounded successor request is appropriate. High-impact routes should require a fresh completeness check after that successor.max_messagesindicates the response reached its message limit. The application should inspect the workflow state before continuing because another model turn can produce another tool request or extend the same task.content_filtercalls for a policy outcome. Record the reason, withhold incomplete output from downstream automation, and route the case according to the application's safety procedure. The policy should exclude unchanged automatic replay.steeredbelongs to the WebSocket flow. OpenAI documents that steering stops at a safe output boundary and can be followed automatically by a successor response carrying queued input. Correlate the predecessor and successor, then accept only the completed result required by the route.
The ceiling itself is explicit: OpenAI defines max_output_tokens as the upper bound covering visible output and reasoning tokens. That makes limit selection part of LLM API parameter allowlisting, while recovery remains an application decision.
The policy gate belongs before every consumer
Place one acceptance gate between the provider adapter and each consumer of response data. The adapter normalizes the provider response, but it should preserve the original response ID, status, reason, output items, and usage fields. The gate evaluates route policy against that normalized object.
A support-chat route may permit display of clearly labeled partial prose after max_output_tokens. A claims workflow that expects a complete structured object should withhold the entire result. An agent route should stop before tool execution when the response or relevant output item remains incomplete. Each route needs its own contract.
The gate should produce one of a small number of application outcomes: accept, withhold, request human review, or permit a bounded continuation. A generic retry flag hides the required distinction. Retries can duplicate cost and can repeat a content-filter outcome without changing the underlying request.
This follows the same route-specific logic used for per-route AI policies. The route gives the stop reason operational meaning. A ceiling hit during draft generation carries a different consequence than a ceiling hit during a model-generated approval explanation.
Streaming clients need a final-event check
Streaming can hide the failure because useful text has already crossed the screen. OpenAI's Responses streaming event reference defines response.incomplete as the event emitted when a response finishes incomplete. The client should treat deltas as provisional until a terminal event arrives and the final response object passes policy.
Keep a visible buffer boundary between presentation and action. Text can render progressively in a chat interface, but downstream actions should wait for terminal acceptance. Structured fields should stay in a staging object until completion and schema validation pass. Tool-call candidates should remain inert until that gate passes.
The physical detail is mundane: a green check beside the final token can convince an operator that the response finished. The terminal status should control that icon; stream closure and the last text delta are weaker signals.
Network interruption is a separate condition. A missing terminal event should enter an indeterminate branch, with retrieval or reconciliation performed by the application. Never infer completed because the socket closed cleanly.
Unknown reasons are compatibility events
Provider schemas can change during an application's lifetime. A reason outside the accepted set should produce a safe application outcome and a high-signal compatibility alert. Store the raw value, SDK or adapter version, response ID, route, and policy version. The alert should name the exact enum mismatch so an engineer can compare it with current OpenAI documentation.
An unknown reason belongs in the compatibility branch. Coercion into max_output_tokens creates the most permissive recovery behavior for a condition the application has never evaluated. The correct default is operational withholding with preserved evidence.
Version the accepted reason set beside the route policy. A provider adapter update can then add a new reason through a reviewed change, a fixture, and a release test. AI audit log schema gives the record a stable home without storing the full sensitive response by default.
The decision record should link every successor
For each incomplete response, record the authenticated caller supplied by the application, application route, provider response ID, status, raw reason, model route, policy version, output-item identifiers, and decision. Add protected digests for the request and retained partial output when correlation requires them.
A continuation or retry needs a new record with its own response ID. Link it to the predecessor and state the application action that authorized it. For WebSocket steering, preserve the documented predecessor-successor relationship. For a token-ceiling continuation, record the continuation strategy and attempt count.
Set a hard attempt budget for every route. A loop that repeatedly reaches the same ceiling is a policy failure. My blunt opinion is that "retry until complete" belongs nowhere near a production agent.
The test suite should force every documented reason, an absent reason, and one unknown value. Confirm that partial output never reaches a protected consumer on routes that require completion. Also confirm that every permitted successor has a joined record.
DeepInspect
DeepInspect can enforce this policy when an authenticated user or agent sends an LLM HTTP request through the routed proxy and the provider response returns along the same path. The application supplies identity and route context. DeepInspect can inspect the response status and reason, apply the route's acceptance rule, and write a per-decision record before forwarding an accepted result.
Application code still owns user display, continuation prompts, retries, WebSocket workflow state, and tool execution. Direct provider calls, local inference, and traffic that bypasses the authenticated proxy sit outside DeepInspect's boundary. The joined record covers only the routed model exchange and the policy decision made there.
Book a demo today.
Frequently asked questions
- Can an application display partial text after max_output_tokens?
Yes, when the route policy explicitly permits labeled partial display and no downstream decision depends on completeness. Keep the provider status attached to the rendered result. Structured extraction, approvals, and tool execution should wait for a completed successor or human handling under the application's contract.
- Should content_filter trigger an automatic retry?
The application's safety policy should determine the next action. An unchanged automatic replay can repeat the same outcome and spend another request without resolving the reason. Preserve the response ID and reason, withhold operational use of the partial output, and send the case to the route's defined refusal or review path.
- Does response.incomplete mean the HTTP request failed?
It means response generation finished incomplete according to the OpenAI response object. HTTP handling and response-generation status are different layers. Client code should process transport errors first, then evaluate the returned response status and its incomplete reason.