AI API requests and safe response handling

Outcome and preparation

Preparation: Basic Python functions, environment variables and exceptions; Python 3.11+ with standard library. If Python is unavailable, trace on paper and label execution unverified. No paid tools or real operational data.

What you will be able to do

• Translate a supported synthetic request and inspect text, usage and completion status.
• Distinguish simulated permanent and transient failures, and state live recovery limits.
• Record the actual runtime, fixture revision and verification result; identify the SDK/model evidence required for live reproduction.

Keep repaired code, first/corrected results, actual runtime/fixture revision and limitation note. This is a teaching contract, not a live SDK parser or security boundary. Watching and review completion do not establish demonstrated capability.

Define the bounded request

An API is an interface your code calls. For a generation task, specify the input and instructions, the supported features you need, an output bound and what your application expects back. Do not begin by assuming every provider or model supports the same options.

Our fictional request asks for a short proposal from supplied logistics facts. It is a drafting request, not permission to send messages or change a system. Our simulated capability declaration supports streaming but does not support reasoning controls or schema output. Requesting an unsupported feature must fail before creation of the request.

Tokens are units used by a model’s tokenizer, not a guaranteed number of English words. A token limit bounds generation according to the endpoint’s rules; it does not guarantee a complete or correct answer. The exact live fields and capabilities belong in the versioned reference.

Our request contains only allowed fields. A feature typed into a generic dictionary is not automatically available. Inspect validate_request: it returns a clear error for an unsupported request before the reducer processes any response fixture.

Inspect the synthetic input

{
  "input": "Fictional team: six people, 40 requests weekly, about 18 minutes each. Propose a two-week trial; no savings have been measured.",
  "max_output_tokens": 128,
  "stream": true
}

Capability declaration: stream: true, reasoning: false, schema: false. Predict the error before running:

python worked-example.py unsupported

Validation rejects unsupported schema before reducing events; this is a fixture check, not a provider rejection.

Map provider differences

Different APIs organize requests and responses differently. The lesson’s dated examples place OpenAI Responses instructions and input in their respective fields, and Anthropic Messages system instructions separately from message content. These are illustrative reference examples, not the local fixture format. Check the actual version before implementation.

An adapter translates a supported request into that interface and maps the returned fields to your application’s contract. Preserve the request ID, text, terminal status, refusal information and known or unknown usage. Do not select behavior only by provider name or by whether the text is empty.

If a feature is unsupported, reject it explicitly or choose a documented alternative. Do not silently drop it and claim equivalent behavior. History must be deliberately supplied or managed by the application according to the chosen interface. Neither a stronger model nor a chat subscription establishes API access, credit or permission to use real data.

Our existing B3 offline pack lets you practice this mapping. Its Messages adapter is deliberately unfinished. Later you will implement it, compare against the worked example only after your attempt, and record what its tests do and do not establish.

Read a complete simulated response

Now run the complete fixture. These events come from a local JSON file. Nothing contacts a model. The reducer receives text chunks and a completed event. It preserves the fixture ID and usage. The final status is complete and no refusal occurred, so our application may pass this result to its next inspection step.

That is transport-contract readiness, not factual correctness. Before using the draft, compare its claims with the supplied source. A complete response can still invent a result. Today’s fixture uses authored text; its passing status does not measure model reliability.

Notice that usage may be absent. Unknown usage should remain null or explicitly unknown; it must not become zero. Zero is a numerical claim. We record only safe metadata here, not raw keys or sensitive prompt content.

Run and compare

python --version
python worked-example.py complete

Expected fixture trace: ID mock-01; complete status; release true; text “We propose a two-week trial. Savings remain unknown.”; supplied usage 31 input and 12 output tokens. Record your observed output; the expected trace is not your execution evidence.

Streaming and the misleading success

Streaming lets an interface show text before the response has completed. That can make progress visible, but chunks are provisional. The cancelled fixture contains readable text and then stops with cancellation. The reducer reports partial, preserves the request ID and leaves missing usage unknown. It does not release the text as a finished result.

Here is the mistake we want to catch: “If there is any text, the call succeeded.” Our starter deliberately makes that decision. It would accept the cancelled fixture because the text is nonempty. Predict what happens with a refusal containing explanatory text.

A refusal is also not a completed answer for the requested task. The same shortcut would accept it. Repair the decision by checking the terminal status and refusal flag, not merely the string.

For this local contract, release requires complete status and no refusal. The code also rejects unknown or contradictory event sequences. A stream that ends without a terminal event stays partial. An error after completion is invalid in our fixture contract. These are local validation rules, not a claim that every SDK emits the same event sequence.

python worked-example.py cancelled
python starter.py refusal

The deliberately unfinished starter contains return bool(result["text"]). Predict why this accepts provisional/refusal text before changing only should_release in your own copy. Keep the distributed starter unfinished and recheck all fixtures after repair.

Failures and bounded recovery

Permanent authentication, permission or invalid-request failures need correction. Repeating the same broken request is not a repair. Some connection, rate-limit or server failures may be transient, but retry policies depend on the endpoint, SDK and operation. Check the installed version and choose one owner for retries.

Do not wrap an SDK retry loop in another loop without understanding how the attempts multiply. A timeout per attempt is different from an overall deadline. A budget caps retry attempts and cost exposure; it does not establish that a real network deadline was enforced.

Also distinguish generating a draft from a consequential downstream action. Retrying text generation is not permission to resend a message, make a purchase or repeat a transaction. Our lab does none of those actions. A cancelled or ambiguous action needs its own safe recovery policy.

Use the existing B3 pack to inspect permanent failures, transient recovery and simulated budget/deadline failures. Those tests simulate policy decisions; they do not establish live transport behavior. If you cannot explain the retry owner and stopping rule, do not claim your application is safely bounded.

Reproduce and inspect the evidence

Run the supplied worked-example tests locally. Record the Python version, fixture revision, command and observed output. Do not copy a passing result from the page and call it your execution.

For the existing B3 pack, read the README first. Run its tests against the starter to observe the unfinished adapter. After your attempt, set LAB_IMPL to worked_example and rerun to inspect the supplied solution. Clear that setting before checking your starter again. Keep your original failure, correction and recheck separate.

Our supplemental streaming fixtures exercise a smaller release decision. They complement the existing adapter practice; they do not replace the full B3 tests. Passing both still leaves live SDK integration, actual provider capabilities, transport timing and factual output quality unverified.

If you choose live practice in the future, use separately authorized data and access, verify the model and SDK, pricing and limits, and record the actual request and response safely. This tutorial does not ask you to create an account or run a paid call. A storage option in an API request is not a blanket promise of zero retention; review the current provider policy and organizational approval.

python --version
python -m unittest discover -p "test_reference.py"
python -m unittest discover -p "test_learner.py"

Reference tests are expected to pass; learner tests deliberately fail before repair. Fixture revision: tutorial-pilot-2026-10-06. Keep observed results, not copied green output.

Runtime and fixture revision:
Command:
Prediction:
Observed first result:
Correction and reason:
Observed recheck:
What executed locally:
What remains unverified:

Independent practice

Feedback and transfer

Retrieve without the solution: text arrives, no terminal event arrives, then the connection ends. Explain status, unknown usage and checks before acting. Continue to local models.

Our answer is in the practice workspace. Write your attempt there and run the checks. Then “Compare with our answer” opens, and so does the full feedback here. Go to the workspace.