OpenAI Output Item Status Validation Before Downstream Use
The OpenAI Responses API returns a heterogeneous output array containing messages, reasoning, function calls, and other item types. Status fields differ across those item schemas, so top-level completion leaves an item-level validation step. This guide defines a type-aware acceptance gate for streaming and non-streaming clients before text, structured data, or tool calls reach downstream systems.

The OpenAI Responses API returns an output array of typed items. A message is one item type. Function calls, reasoning, computer actions, and provider tool calls use other shapes. Several item types also carry their own status. Code that checks only the top-level Response status and then loops over every output object as finished data collapses two state machines into one. I want a type-aware item gate between the provider adapter and every downstream consumer.
TL;DR
- Validate the top-level Response first, then validate every output item by its type-specific schema and status set.
- Treat output items as a discriminated union; one universal status allowlist will accept invalid states or reject valid ones.
- Streaming deltas remain provisional until the item and response reach terminal events and pass policy.
- Keep incomplete, failed, unknown, and unsupported items away from tool execution and protected business workflows.
Responses use items as the unit of model output
OpenAI's migration guide for the Responses API explains the structural change clearly. Chat Completions uses messages, while Responses uses Items. A message is one Item type. Other model actions include function_call and function_call_output. Items remain distinct because they represent different units of context.
That design requires dispatch on the type field before reading any other fields. A message consumer can inspect message content. A function-call consumer expects a name and arguments. It also expects a call identifier. A reasoning item follows another contract. Built-in tool calls have their own fields and lifecycle.
The acceptance sequence should be mechanical: validate the response envelope, require a recognized item type, select that type's schema, validate required fields and status, then apply route policy. Preserve the original item ID and array position throughout the process.
A generic loop that extracts every content field may look clean in a code review. It also erases the distinctions the API intentionally exposes.
Status sets differ by item type
The OpenAI response schema documents in_progress and completed for returned message items. It also documents incomplete. Other item variants expose different state sets. For example, image generation includes generating and failed, while some computer-call output structures include failed beside the common lifecycle values.
One global enum therefore creates a bad contract. Allowing failed for every item can make a message appear valid under a state its schema never defines. Rejecting generating everywhere can break a client that legitimately handles image-generation progress. The item type selects the status grammar.
Build a registry keyed by provider API version and item type. Each entry should define required fields, accepted statuses, terminal statuses, and the application consumers permitted to see that item. Unknown status values should enter a compatibility branch with the raw value preserved.
This registry extends LLM API parameter allowlisting to provider output. Request policy controls what can leave. Output validation controls what the application may trust on return.
Top-level completion leaves item validation open
A completed Response means response generation reached its documented top-level outcome. Item acceptance remains a separate check because the output array is a union of independently structured objects. The application still has to confirm that each item is recognized and internally consistent. It must also confirm that the item is allowed for the route.
Consider a route that expects one completed assistant message and forbids tool calls. A completed response containing a valid function-call item violates that route contract even if every provider field is well formed. Another route may permit function calls but require each call's arguments to match a registered tool schema before the application considers execution.
Define output cardinality inside the same route contract. A classification route may require exactly one completed message with one structured content part. An agent route may accept several function calls. A chat route may allow reasoning metadata and one user-visible message. The policy should name those shapes and reject output arrays outside the accepted set.
The per-route AI policy pattern gives these differences an owner and a version.
Streaming needs two terminal checks
The Responses streaming event reference exposes item lifecycle events such as output-item creation and completion, followed by a terminal response event. A client can receive content deltas while the item is still in progress. At that moment, those bytes qualify as presentation material. Business acceptance comes later.
Keep one staging record per response ID and output index. Apply deltas only to the matching item. When the item terminal event arrives, validate the assembled object against its type-specific schema and status. When the response terminal event arrives, validate the envelope. Release the item to a protected consumer only after both checks pass.
This ordering also handles an incomplete response containing apparently completed text beside another unfinished item. The route policy can withhold the whole response or release only a documented subset. Record that choice in the route contract.
On a screen, the dangerous detail is a tool card with a bright blue "Run" button while arguments are still arriving. Disable the control until item and response acceptance finish.
Unknown types and statuses need a compatibility branch
Unknown item types and missing discriminators should produce a stable application outcome and block the default parser. New status values should produce the same result. Provider output can evolve after a client ships. Preserve the response ID, item ID, output index, raw type, raw status, adapter version, route, and policy version.
For user-facing chat, the application may show a neutral error while retaining the unknown object in protected diagnostics. For automation, the default should withhold dispatch. An alert should distinguish a provider schema addition from malformed data. It should also separate both from an application adapter bug.
Avoid rewriting an unknown type into a message. That loses fields and can turn a new action-bearing item into text that another component trusts. Avoid treating a missing status as completed unless the selected item schema explicitly permits the field to be absent for that retrieval mode.
Versioned fixtures make the change reviewable. Add one specimen for each supported type and terminal state. Add negative cases for unknown values and missing fields. Include cross-type fields as well.
Tool calls require validation before execution
A function_call item is a model proposal. OpenAI's function calling guide assigns execution to application code and says a response can contain multiple calls. It can also contain one call or none. The application should first validate item type and status. It should then validate the tool name and parse arguments against the registered schema.
Authorization at the target system remains a separate decision. A valid, completed function-call item proves only that the provider returned a well-formed proposal under the API contract. It says nothing about the authenticated caller's permission to change a customer record or issue a refund.
AI tool call policy enforcement begins after this validation. Item validation protects the parser and workflow state. A separate authorization decision protects the action. Link their records with the response ID and item ID. Preserve the call ID as well, but keep the outcomes distinct.
I would block a deployment that executes a call directly inside the JSON deserializer. Parsing and acting need a visible policy seam.
Audit records should preserve the item decision
Record one decision for each output item that enters a protected consumer. Include the authenticated identity supplied by the application, route, provider response ID, item ID, output index, item type, raw status, schema version, policy version, and acceptance outcome. Store a digest of sensitive content or arguments when full payload retention is unnecessary.
Rejected items belong in the record as well. An auditor should be able to see that a response contained an unsupported action and that the application withheld it. If the route accepts only one message, record the cardinality rule that rejected a second message or a function call.
The test plan should mix item types in one response fixture. Include a top-level completed response with an incomplete message and a supported type with an unknown status. Add a new type and a missing discriminator. Include a function call with malformed arguments. Confirm that no rejected item reaches the downstream mock.
AI audit log schema can carry the joined response and item decisions while keeping the raw provider payload in a separately controlled store.
DeepInspect
DeepInspect can apply output-item policy to authenticated user or agent traffic deliberately routed through its HTTP proxy to an LLM endpoint. It can inspect the returned response envelope and typed items, evaluate the application route's accepted shapes, and record the policy decision before forwarding an accepted response. The configured decision can allow or deny forwarding. It can also withhold the response.
The application owns stream presentation, provider adapter updates, item assembly, tool execution, and target-system authorization. Local model calls and direct provider traffic sit outside the proxy boundary. Other bypass paths sit outside it as well. DeepInspect's record covers the routed HTTP exchange and its response-policy decision.
Book a demo today.
Frequently asked questions
- Is a completed Response enough to use every output item?
Completion at the Response level is only the first gate. Validate the envelope, then dispatch each item by
typeand apply that type's schema and status rules. Apply route policy next. A completed response can still contain an item type the application route forbids or fields the consumer cannot safely process.- Should clients ignore output item types they do not use?
A presentation-only client can withhold unsupported items and record them. Automation should treat an unexpected action-bearing item as a policy event. Silent dropping hides provider or prompt behavior that may matter during incident review.
- Can streaming text be shown before the item completes?
A chat interface can render provisional text when its product contract labels and handles that state. Structured extraction, approvals, tool execution, and protected business decisions should wait for item-level and response-level terminal validation.