Provider SDKs and the differences that actually matter

Read these first

• Chat API shape

What you will know

• Make the same call through two different provider SDKs

  Doing the same task twice teaches you which parts are the model and which are the vendor's wrapper.

• Compare one capability across two providers by running the same request and recording the resulting schema, errors, and limits

  A field may be rejected, silently ignored, or implemented with different defaults even when both SDKs expose similarly named controls.

• Read a provider's API reference and find the parameter you need

  The reference is the source of truth; blog posts and tutorials go stale within months.

• Trace one SDK request to the wire and reproduce it with raw HTTP, including streaming and error handling

  Hidden headers, serialization choices, retries, and stream framing can change behavior or obscure the real failure.

• Decide when to drop to raw HTTP

  When you need a parameter the SDK has not exposed yet, or you are debugging what actually goes over the wire.

Chapters

1. 1

   Provider SDKs

   A provider SDK is the client library a model vendor publishes for your language, sitting on top of the HTTPS endpoint you could call with curl. Send the same prompt through two vendors' clients and sort what you see into two piles: differences a thin mapping layer absorbs completely, and differences that change the tokens sent, the sampling applied, or the amount billed.

   Read chapter
2. 2

   Unsupported parameters

   Pass a sampling control such as top_k through a shared internal wrapper and three things can happen: a 400 naming the field, silent acceptance with no effect, or the client stripping the unknown argument so one path samples differently from the other. Work from the provider's API reference rather than a blog post, and record schema, defaults, errors and limits for the same request on both sides.

   Read chapter
3. 3

   Request headers and wire capture

   Lift the exact JSON body a provider client sends, replay it with curl and an API key, and watch it come back 400. The missing pieces are the headers the client added for you — an API version, a beta flag, a content type — plus the serialisation choices it made. This chapter covers capturing the real request from the process that made it, and reproducing it on raw HTTP byte for byte.

   Read chapter
4. 4

   Streaming response framing

   Both major providers stream over Server-Sent Events, and there the agreement stops. One emits named events that finish with a terminal event carrying the stop reason and token usage; the other emits chat-completion chunks with a delta field and a sentinel line. A handler written for the first, pointed at the second, buffers until generation ends and logs zero tokens — here is how to parse each framing without an SDK in the way.

   Read chapter
5. 5

   Built-in retries and backoff

   Swap a hand-rolled client for the official provider SDK and one logical call may become several HTTP calls, because 429 and 5xx responses are retried internally with exponential backoff. Error dashboards stay flat while peak-hour p99 triples. This chapter covers finding the retry policy, making each attempt visible in your own metrics, and deciding when to turn it off and own the backoff yourself.

   Read chapter
6. 6

   Error classification across providers

   Context overflow, a content filter, an overloaded backend, an exhausted quota and a malformed body are five distinct conditions, and each vendor reports them its own way: some in the HTTP status, some in an error field on a 200, some only in the terminal event of a stream. Build the classification your own code needs — which conditions are retryable, which are terminal, which are the user's problem — and see what an SDK's typed exception hierarchy does and does not carry.

   Read chapter
7. 7

   Stop reasons and truncation

   Every response says why generation ended, and a response cut off at a cap says so unambiguously on both major providers. Before conceding that a new model is weaker, read that field on the truncated population, then check the three plumbing causes that produce exactly this shape: a different default output cap, a different tokenizer counting the same text, and a wrapper silently clamping the maximum.

   Read chapter
8. 8

   Dropping to raw HTTP

   When a provider capability exists on the HTTP API but not in the language client, the options are forking the client, patching it at runtime, or calling one endpoint over raw HTTP. Try the documented extension points first; when they are not enough, an isolated raw call is the reversible seam — and this chapter covers what you must reimplement on that path, chiefly stream parsing, error classification and backoff.

   Read chapter
9. 9

   Compatibility claims and provider abstractions

   An OpenAI-compatible endpoint promises request and response schema; it is silent on defaults, tokenizer, stream framing, rate-limit behaviour and error taxonomy — the things that fail in week three rather than on the first call. The same ceiling applies to an in-house layer over three providers, which can only surface what all of them do. What keeps that from killing the layer is a typed, observable escape hatch and a written rule for reaching through it.

   Read chapter