OpenAI & Claude APIs

The closing post is a catalog of the boring, recurring failures that take down LLM apps — chosen precisely because they are common rather than exotic. The framing is that learning these from a list is far cheaper than learning them from a 3 a.m. postmortem. Each mistake is paired with a concrete fix so the post is actionable, not just cautionary.

The first and most damaging mistake is putting your API key in client-side code. Any key shipped to the browser is visible to every visitor through developer tools or network inspection, and a stolen key can run up unbounded charges or be abused against the provider's terms before you notice.

The rule is absolute: API keys live only on servers you control. The browser should never hold one. This single mistake has generated countless leaked-key incidents, often discovered only when a surprise bill arrives. There is no safe way to embed a provider key in a public client, so the fix is architectural rather than a matter of obfuscation.

The fix is the proxy pattern. The frontend calls your own backend endpoint with just the prompt and no secret. The backend, which holds the key in its environment, makes the actual provider call and returns the result. The key never crosses the network to the client.

This backend layer is also where you add the rest of your defenses — authentication, rate limiting per user, input validation, and logging. So the proxy is not just a security fix; it is the natural home for every other production concern. If you build it from the start, most of the other mistakes in this post become easy to prevent.

The second mistake is ignoring stop reasons, which leads to silently shipping truncated output. When max_tokens is set too low, the model is cut off mid-thought, and code that does not inspect the stop reason will happily parse and use the broken fragment as if it were complete.

The fix is twofold: set max_tokens with real headroom for the expected output, and always read the finish/stop reason before trusting the text. This is especially critical when the output feeds another system — a truncated JSON object or an unfinished sentence passed downstream causes failures that are hard to trace back to their true cause.

This decision tree turns stop-reason handling into a simple branching rule. If the stop reason is max_tokens, the reply was cut off — raise the limit and retry. If it is end_turn (or 'stop'), the reply is genuinely complete and safe to use. Anything else — a tool-use request or a refusal — needs its own handling path.

Encoding this as explicit logic rather than an afterthought makes your integration robust to the full range of ways a generation can end. Most bugs in this area come from assuming there is only one outcome — a complete reply — when in fact the API is telling you exactly which of several outcomes occurred, if you bother to read it.

The third mistake is mixing the two providers' request formats. OpenAI expects the system prompt as a message inside the messages array and treats max_tokens as optional; Claude expects system as a top-level field and requires max_tokens. Copying one provider's request shape onto the other yields confusing 400 errors that do not obviously point at the cause.

The fix, consistent with the whole day, is a thin per-provider adapter that owns each shape, so the two formats never bleed into each other. When the formats are isolated, a 400 is easy to localize to one adapter, and your calling code never has to remember which dialect it is speaking.

This compare diagram lists the specific traps side by side so they are easy to memorize. On the OpenAI side: system goes in the messages array, you read the reply from choices[0].message, and max_tokens is optional. On the Claude side: system is top-level, you read from the content blocks' text, and max_tokens is required.

The required-versus-optional max_tokens difference is the single most frequent stumbling block when moving from OpenAI to Claude, because the omission that works fine on one API is a hard error on the other. Keeping this table in mind — or better, encoding it in an adapter — eliminates an entire class of errors.

The fourth mistake is trusting model output to be valid, schema-conforming JSON. Even with JSON mode enabled, the model guarantees valid JSON syntax, not that the structure matches what your code expects. A field can be missing, mistyped, or nested differently, and a bare json.loads followed by direct field access crashes on the first such response.

The fix is defensive parsing: validate the parsed object against an explicit schema and have a fallback or retry path when it does not fit. Treat model output as untrusted input from an external system, because that is exactly what it is — capable of surprising you precisely when you are least prepared for it.

The code shows the defensive pattern with Pydantic. A City model declares the expected fields and types; constructing it from the parsed JSON validates the structure in one step. Wrapping both the json.loads and the model construction in a try/except catches malformed JSON and schema violations alike, routing failures to a retry-or-fallback path instead of crashing the request.

This pattern scales to arbitrarily complex schemas and gives you a single, clear place where bad model output is caught. It converts an entire category of runtime crashes into a controlled, observable branch you can log, retry, or degrade gracefully — which is the difference between a robust integration and a fragile one.

The fifth mistake is having no rate-limit or retry strategy. Both APIs return 429 responses when you exceed your rate limit and occasional 5xx errors under load; code with no resilience turns each transient blip into a user-facing failure. This is the most common cause of flaky LLM features that 'work most of the time'.

The fix combines three things: exponential backoff with jitter so retries do not synchronize into a thundering herd, respecting the Retry-After header the API sends to tell you exactly how long to wait, and a hard request timeout so a single slow call cannot hang your endpoint indefinitely. Together these make your integration degrade gracefully under exactly the conditions where naive code falls apart.

The final checklist is the deployable summary of the entire day. Keys stay server-side and are rotated. max_tokens is set and the stop reason is checked. Each provider has its own adapter. JSON output is validated against a schema. Every call has backoff and a timeout. Usage and errors are logged.

Running down this list before shipping catches the great majority of LLM integration incidents before they happen. None of the items are difficult individually; the value is in doing all of them, because production failures tend to find whichever one you skipped.

That closes Day 92. You now have the full arc: the vocabulary of both APIs, why the provider choice is an architecture decision, how a request becomes tokens, a runnable client for both providers, and the mistakes that separate a demo from a deployable system. You can build against OpenAI and Claude with eyes open.

The series continues into Day 93, but the practical takeaway from this day stands on its own: isolate the provider, count tokens, check stop reasons, validate output, and retry intelligently — and your LLM features will hold up under real traffic.