What you’ll be able to do
- Know what layer you are working at when a call fails
- Explain what the SDKs add over raw REST
- Recognise when a persistent connection is the right transport
- Debug across the SDK / REST boundary
What you need to know
SDKs are wrappers, and that matters when things break
The official SDKs wrap the same REST API you could call with an HTTP client. They add ergonomics — typed request and response objects, streaming helpers, retry and backoff defaults, pagination, error classes — but nothing they do is unavailable at the HTTP layer.
Why the blueprint cares: when a call fails, you need to know whether you're looking at an SDK-level problem (a typed field you set wrong, a helper's default timeout) or an API-level one (a 400 from a malformed body, a 429 from your account's limits). Candidates who treat the SDK as opaque debug in the wrong place.
Reading an error back to its layer
- A validation error thrown before any request leaves your process → SDK-level, your call shape
- A
400returned from the service → the request body was malformed; the SDK passed along what you gave it - A
429or529→ account limits or service load; neither is a code bug - A timeout with no response → transport or the SDK's configured timeout, not model behaviour
When a persistent connection is the right shape
Standard request/response covers nearly everything. Websockets exist for genuinely bidirectional, persistent interaction — where both sides send messages over a held-open connection rather than one side asking and the other answering.
Worth distinguishing from streaming, which people conflate. Streaming is still one request and one response; the response simply arrives in pieces over the same HTTP connection. That covers "show the answer as it's written." A websocket is a different transport for a different interaction shape, and reaching for it when streaming would do is over-engineering.
Key concept
The SDKs wrap REST and add ergonomics, not capability. Knowing which layer an error came from tells you where to fix it. Streaming is a chunked response; a websocket is a different transport entirely.
Practice scenario
Work it through, then open this
It never left the process — this is a call-shape problem, and retrying reproduces it forever. Read the error back to its layer: local validation means fix the call, a 400 means fix the request body, and only 429 and 529 are transient conditions that backoff addresses.
Build exercise — Read an error back to its layer
Beginner · 15 min
What you’ll learn
- Knowing whether a failure is SDK-side, request-side, or account-side
-
Deliberately break a request three ways: a malformed field the SDK will reject before sending, a body the API will reject with a 400, and a rapid loop that trips a rate limit.
- Why: Knowing which layer threw tells you where to fix it, and the three feel similar until you’ve seen them side by side.
- You should see: Three visibly different failures — a local exception, a server 400, and a 429.
-
For each, write the correct response in one line: fix the call shape, fix the request body, or back off and throttle.
- Why: Matching response to layer is the tested skill, not knowing that errors exist.
- You should see: Three different responses. If you wrote ‘retry’ for more than one, re-check the 400.
Exam traps
Treating a 400 as an SDK bug
The SDK sent what you constructed. A 400 means the request body was wrong — audit the schema, do not retry.
Reaching for websockets when streaming is what is needed
Streaming is one request delivered in chunks and handles progressive display. A websocket is a different transport for genuinely bidirectional interaction.
Retrying a request that failed SDK-side validation
It never reached the network. The same call will fail identically every time until the shape is fixed.