Skip to main content

5.2 Technical fundamentals

6.1% of the exam — the second-heaviest skill. It is the plumbing beneath every other domain: SDKs wrapping REST, transports, connections, and configuration.

SDKs wrap the REST API​

Every SDK call is an HTTP request to the same endpoints. The SDK exists to remove the parts everyone gets wrong.

The SDK gives youWhat you would otherwise hand-roll
Credential resolutionEnv var, auth token, CLI profile, workload identity federation, in a defined precedence
Typed request and response modelsHand-written interfaces that drift from the API
Typed exception classesString-matching error messages
Automatic retries with backoffYour own retry loop (defaults: 2 retries on 408/409/429/5xx and connection errors)
Streaming helpersManual SSE parsing and event reassembly
Pagination helpersCursor bookkeeping
Timeout defaults and scalingA fixed timeout that breaks on long generations
Provider clientsSigning and endpoint construction for Bedrock, Vertex, Foundry

Two rules:

  1. Do not mix an SDK with raw HTTP in the same project. Pick the SDK when one exists for your language; use raw HTTP only when there is no SDK or the project genuinely is a shell/cURL project.
  2. Do not reimplement SDK functionality. Use finalMessage() / get_final_message() instead of wrapping stream events in a promise; use the SDK's types instead of redefining equivalents; use the typed error classes instead of parsing messages.

Client configuration that bites​

SettingDefaultTrap
timeout10 minutesUnits differ: seconds in Python/Ruby, milliseconds in TypeScript, Duration/TimeSpan in Java/C#
max_retries2Timeouts are retried, so worst-case wall clock is timeout × (retries + 1)
base_urlFirst-party APIDo not point the first-party client at a partner platform — use that platform's client class
AuthANTHROPIC_API_KEY, then an auth token, then a CLI profile, then federationAn unset API key does not mean there are no credentials

Transports: HTTP, SSE, and WebSockets​

TransportDirectionClaude usageRight for
HTTP request/responseClient → server, one shotPOST /v1/messages non-streaming; batches; filesEverything that fits in one round trip
Server-sent events (SSE)Server → client, unidirectional stream over one HTTP responseMessages API streaming; Managed Agents session eventsToken-by-token output, progress, long generations
WebSocketsFull duplex, persistentNot how the Messages API is calledYour own client↔server channel: pushing deltas to a browser, bidirectional voice or collaboration, cancelling work mid-flight
PollingClient-initiated, repeatedBatch processing_statusLong-running server-side jobs with no push channel

The realistic architecture for a chat UI: the browser holds a WebSocket (or SSE) to your server, and your server holds an SSE stream from the Claude API, forwarding deltas. The API key never reaches the browser.

Never call the API from the browser

A key shipped to a client is a leaked key. Requests go through your backend, which holds the credential, enforces the user's authorization, applies rate limits, and logs usage. This is also the only place you can validate output before it reaches a downstream system.

Connection and concurrency management​

PracticeWhy
Reuse one client instanceConnection pooling and keep-alive; constructing a client per request wastes handshakes
Bound concurrency with a semaphore or worker poolUnbounded fan-out trips 429s and makes latency worse, not better
Backoff with jitter, honour retry-afterSynchronised retries create a thundering herd
Stream long generationsAvoids request timeouts, gives progress, and is required for very large max_tokens
Set an end-to-end deadlinePer-attempt timeouts multiply with retries
Make retried operations idempotentA retry after a timeout on a succeeded call otherwise duplicates side effects
Handle backpressureIf your consumer is slower than the stream, buffer with a bound or cancel

Serialization and data handling​

  • Deterministic JSON for anything inside a cached prefix — stable key order, no timestamps, no UUIDs.
  • Base64 with no newlines for inline images and PDFs; prefer the Files API when the same asset is reused.
  • Size limits are real: 32 MB per request, 600 pages per PDF (100 on 200K-context models).
  • UTF-8 throughout, and never truncate input silently to make it fit — chunk it or say so.

Configuration and environment hygiene​

ItemWhere it belongs
API keys and tokensEnvironment or a secret manager — never source, never a committed settings file
Model ID, effort, max_tokens, timeouts, retry policyEnvironment-specific config, changeable without a code edit
Beta headersConfig, behind a flag — they are part of the request contract
Region / inference_geoConfig, driven by the residency requirement
Logging destination and redaction rulesConfig, with PII rules enforced in code

Quiz​

  1. Question 1

    A browser-based chat UI must render tokens as they arrive. Which architecture is correct?

  2. Question 2

    Which statement about the official Anthropic SDKs is correct?