Build Reliable OpenAI Responses API Workflows

Responses are typed items, not one string

The Responses API accepts instructions and input, then returns a response containing status, usage, and typed output items. An item may be a message, function call, tool result, reasoning item, or another supported type. Message content can also contain different content-part types.

Convenience fields such as output_text are useful for simple text-only cases, but production code must inspect the response status and the item types its contract permits. Reject or route unknown types instead of silently flattening them into trusted text.

Choose who owns conversation state

A workflow can send the complete history itself, link a request with previous_response_id, or use a provider conversation object where appropriate. Each option changes persistence, retention, deletion, audit, branching, and recovery behavior. Record the chosen state owner in the design.

Do not assume that linking a response automatically satisfies your privacy or retention policy. Decide which inputs, outputs, identifiers, summaries, and audit evidence the application stores; apply minimization and access controls; and verify current provider storage behavior for the selected request settings.

Configure the SDK boundary

Load OPENAI_API_KEY from the runtime environment or a managed secret store and fail closed when it is unavailable. Keep the key out of source, prompts, telemetry, browser code, and learner submissions. Scope, rotate, and revoke it through an operational process.

Treat the model identifier, timeout, output limits, retry budget, and storage choice as reviewed configuration. Verify supported values in current official documentation instead of freezing a tutorial model name into reusable code.

Typed Responses API boundary

typescript

import OpenAI from "openai";

const model = process.env.OPENAI_MODEL;
if (!process.env.OPENAI_API_KEY || !model) {
  throw new Error("OpenAI API configuration is incomplete");
}

const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
const response = await client.responses.create({
  model,
  instructions: "Return a concise, evidence-linked risk summary.",
  input: [{ role: "user", content: approvedInput }],
  store: false,
});

if (response.status !== "completed") {
  throw new Error(`Response did not complete: ${response.status}`);
}

for (const item of response.output) {
  if (item.type !== "message") continue;
  for (const part of item.content) {
    if (part.type === "output_text") await handleValidatedText(part.text);
    else if (part.type === "refusal") await handleRefusal(part.refusal);
    else throw new Error(`Unhandled content part: ${part.type}`);
  }
}

Validate status and output

Handle completed, incomplete, failed, cancelled, queued, and in-progress behavior according to the current contract and your execution mode. An incomplete response needs its incomplete details examined; a function call needs tool handling; a refusal needs a user-safe path. Never label every non-empty response as success.

Validate required content, schemas, allowed values, citations, lengths, and business rules before downstream use. Separate provider transport success, model completion, application validation, and external postcondition verification in your state machine.

Recover and observe with bounds

Classify failures before retrying. Rate limits and transient service failures may be retried with provider guidance, jitter, a maximum attempt count, and an end-to-end deadline. Authentication, authorization, malformed requests, and validation failures require correction rather than an unchanged retry.

Record correlation identifiers, application and prompt versions, configured model reference, state mode, latency, usage, response status, item types, validation result, retry count, and terminal workflow state. Redact or omit credentials, sensitive inputs, unrestricted outputs, and provider identifiers that are not required by the approved telemetry policy.

Practice activity

Design a production-shaped Responses API client

Define a request contract with environment-based credentials, configurable model, instructions, typed input, storage choice, timeout, retry budget, and correlation identifier.
Choose one conversation-state mode and document persistence, retention, deletion, branching, privacy, and recovery behavior.
Implement or diagram handlers for completed text, refusal, function call, incomplete response, unknown item, invalid output, authentication failure, rate limit, timeout, cancellation, and provider failure.
Create deterministic fixtures and a telemetry allowlist that prove each terminal path without exposing credentials or sensitive prompt content.

What to produce

A secret-free client implementation or design with typed item handling, explicit state ownership, validation, bounded retries, and deterministic tests.
A state and telemetry record showing configuration versions, correlation, status, item types, usage, validation, retry, and terminal outcome under a documented privacy policy.

Reflect before continuing

Which state-management choice did you make, and what deletion and recovery evidence proves that the application—not an assumption—controls the learner's data?

Build Reliable OpenAI Responses API Workflows

You will be able to

Responses are typed items, not one string

Choose who owns conversation state

Configure the SDK boundary

Validate status and output

Recover and observe with bounds

Design a production-shaped Responses API client

What to produce

Reflect before continuing

Sources and verification

Make it stick.