Every AI API works the same way: an endpoint, a key, a request body, a response body. The details change — the pattern doesn’t. Keys that never touch your source, one Python and one TypeScript client, the raw HTTP underneath, and what a 429 really means.
An endpoint (the URL), an API key (authentication), a request body (what you want), a response body (what you get back). Every provider spells them differently; the shape never changes. The key travels in a header — for Anthropic, x-api-key — and TLS encrypts the connection around it.
POST https://api.anthropic.com/v1/messages · x-api-key: sk-ant-…Keys go in environment variables (export ANTHROPIC_API_KEY=…) or a .env file that is listed in .gitignore. SDKs read the variable by name. If a key ever reaches a repo, a log, or a screenshot, treat it as public: revoke it in the console and issue a new one. Deleting the file does not delete the history.
export ANTHROPIC_API_KEY=sk-ant-… · .env → .gitignoreThe status line is the first diagnosis: 4xx means change the request (401 key, 404 address, 429 slow down with Retry-After), 5xx means wait and retry. Back off exponentially — 1s, 2s, 4s, 8s capped — with jitter so clients don't retry in lockstep. Then count tokens: input and output are billed separately.
1 + 2 + 4 + 8 = 15s · full jitter expected 7.5s · ≈4 chars/tokenAn API call is one structured message in four parts — endpoint, key, request body, response body — so learn the pattern once, keep the key in the environment (and rotate it the moment it leaks), read the status code before the message, and treat tokens as money.
By the end you will be able to make a real call with the Anthropic SDK in Python and TypeScript; explain what the SDK hides and reproduce the raw HTTP request with urllib; name the status families and their first fix (401 key, 403 permission, 404 address, 429 wait with Retry-After, 5xx retry); choose a backoff schedule — 1s, 2s, 4s, 8s capped = 15s, halved in expectation by full jitter; estimate tokens at ≈4 characters each (a 60-word prompt ≈ 80 tokens); compute an example bill from example rates; and rotate a leaked key without pretending that deleting the file was enough.
Every AI API — Anthropic, OpenAI, Google, a local Ollama server — is one structured message sent to an address, and one structured message sent back. Learn the shape once and the schemas become details.
An API (application programming interface) is a contract that lets one program call another. For AI models the call goes over a network, which means it is an HTTP request (HyperText Transfer Protocol): a method, an address, some headers, and a body. The provider answers with a status code, its own headers, and a body. No browser, no clicking — just a message and a reply.
The source draws this as a sequence diagram with two participants: Your Code sends an HTTP request carrying an API key; the API Server answers with an HTTP response in JSON (JavaScript Object Notation). That is the whole picture, and it has exactly four parts:
| Part | Where it lives | Anthropic example (masked) |
|---|---|---|
| Endpoint | the URL you POST to | https://api.anthropic.com/v1/messages |
| API key | a request header | x-api-key: sk-ant-… |
| Request body | JSON sent with the POST | {"model": "claude-sonnet-5", "max_tokens": 256, "messages": […]} |
| Response body | JSON sent back | {"content": [{"type": "text", "text": "…"}], "usage": {…}} |
A URL (uniform resource locator) is more than an address: api.anthropic.com is the host, /v1/messages is the path. The v1 is the API version, pinned in the URL — when a provider ships a breaking change, it usually moves the path rather than silencing the old one. The key is not encryption: TLS (Transport Layer Security) encrypts the connection, while the key identifies your account, authorizes the request, and tells the provider who to bill. That is why losing a key is like losing a payment card, and why the next chapter is entirely about custody.
Pick the transport and the outcome, then watch the four parts travel: the key is injected from the environment, the headers and body go out, the status comes back, and words stream in. The 429 wait is accelerated 30 seconds into about one.
urllib.request — you write all three headers yourself. the key checked out and the body was valid. The four parts never change — only the spelling of them does.
In the exchange, where does your question travel — and what does the API key actually protect?
The source’s rule is one sentence: never put API keys in code. The value belongs in an environment variable or an ignored .env file, the code reads the variable by name, and a leaked key gets rotated — not just deleted.
A key with a spend limit is a bearer credential: whoever holds the string can spend your quota. So the first design rule is custody — the value must live somewhere that never travels with the code.
Pattern one: environment variables. The shell holds the value and passes it to every program it starts. export ANTHROPIC_API_KEY=sk-ant-… sets it for the current shell session; a new terminal starts clean, so people put the line in a shell profile such as ~/.zshrc (a file outside the repository). CI (continuous integration) systems and cloud platforms have their own secret stores that inject environment variables at run time — the mechanism is the same, only the vault differs.
Pattern two: a .env file, listed in .gitignore. Dotenv files keep KEY=VALUE lines next to the project, which is convenient for local development. The convenience is only safe because of one line in .gitignore. And a .env file does not load itself: something has to read it into the process environment. The source’s TypeScript port hand-writes a twenty-five-line loader for exactly this reason — KEY=VALUE per line, # comments, optional quotes — and it lets process.env win, so a real exported variable overrides the file without editing anything.
# ~/.zshrc (or a CI secret, or a cloud secret manager)
export ANTHROPIC_API_KEY="sk-ant-…"
# .env — a convenience copy for local runs, never committed
ANTHROPIC_API_KEY=sk-ant-…
LLM_MODEL=claude-sonnet-5
# .gitignore — the line that makes .env safe
.env
.env.*
# the code never contains a value, only a name
# Python: os.environ["ANTHROPIC_API_KEY"]
# TypeScript: process.env.ANTHROPIC_API_KEY
# SDKs: anthropic.Anthropic() / new Anthropic() read the variable for youWhat leaks actually look like. Note that the leak is rarely a dramatic hack. It is a .env that missed .gitignore; a key pasted as a test fixture; a notebook cell whose output was saved into the .ipynb JSON; a CI log line that printed the environment for debugging; a screenshot with the value visible in a variable inspector; a Dockerfile ENV line baked into every image layer; an error-tracker event carrying the request headers. Code-hosting platforms and providers scan public repositories for credential patterns, and a discovered key can be revoked automatically — but the safe assumption is that anything that reached a remote, a log, or another person is public.
If a key leaks, rotate it. Rotation means: revoke the key in the provider console, create a new one, update every place that needs it (your shell, CI secrets, a deployed service), restart the processes that cached the old value, and only then clean up the repository. Purging history with git filter-repo or BFG is worth doing — but it is cleanup, not a fix. The old key was valid the entire time it was exposed.
Pick a snippet, or paste your own and say where it lives. The scanner is a teaching heuristic — a real repository wants gitleaks or trufflehog in CI — but the leak paths it names are the ones that actually happen.
The classic first draft: the key typed straight into the file that gets committed. Nothing looks wrong until the repo is public.
A key value itself is not the only leak: where it flows matters. Exposure in git history keeps the old key valid until you rotate it in the provider console.
You committed a .env with a live key, deleted the file in the next commit, and added .env to .gitignore. Are you safe?
An SDK (software development kit) is a library that wraps the raw HTTP exchange in typed functions. You create a client, ask for a message, and read the text out of the response — with the key supplied by the environment, never by the code.
Install once, then let the client find the key: pip install anthropic for Python, bun add @anthropic-ai/sdk (or npm) for TypeScript. The source’s Python call is the whole program in miniature — this is the canonical upstream snippet, with the usage line added from the source’s script:
import os
import anthropic
client = anthropic.Anthropic() # reads ANTHROPIC_API_KEY from the environment
MODEL = os.environ.get("LLM_MODEL", "claude-sonnet-5")
response = client.messages.create(
model=MODEL,
max_tokens=256,
messages=[{"role": "user", "content": "What is a neural network in one sentence?"}],
)
print(response.content[0].text)
print(f"Tokens used: {response.usage.input_tokens} in, {response.usage.output_tokens} out")Read it one line at a time, because every line is a design decision:
client = anthropic.Anthropic() — the client looks for ANTHROPIC_API_KEY in the process environment. No argument means no key anywhere in your source, and no key in the traceback if something fails.MODEL = os.environ.get("LLM_MODEL", "claude-sonnet-5") — the model id is configuration, not code. The source’s default is the un-dated Sonnet alias claude-sonnet-5; a dated name pins an exact snapshot, an alias follows the provider’s current build.max_tokens=256 — a hard cap on the output, not the input. The source picks 256 because a one-sentence answer is small; it is also required, so omitting it returns 400.messages=[{"role": "user", "content": "…"}] — a list of turns, with roles user and assistant. One message is still a list; a conversation is the same list with more entries.response.content[0].text — the response’s content is a list of blocks. The first block is a text block here; a model may return several, which is why the index is explicit.response.usage — input and output tokens for this call. This is the receipt; keep an eye on it from your very first request.The TypeScript port is the same program wearing different syntax. Note that await appears because the call is asynchronous — the program does nothing until the answer arrives:
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic(); // reads ANTHROPIC_API_KEY
const MODEL = process.env.LLM_MODEL ?? "claude-sonnet-5";
const response = await client.messages.create({
model: MODEL,
max_tokens: 256,
messages: [{ role: "user", content: "What is a neural network in one sentence?" }],
});
console.log(response.content[0].text);$ python first_api_call.py
A neural network is a stack of differentiable functions that learns patterns
by adjusting weights against a loss signal.
Tokens used: 12 in, 28 outThe prompt "What is a neural network in one sentence?" is 41 characters. At the lesson’s rule of thumb — ≈4 characters per token for English — that is 41 ÷ 4 = 10.25, or about 11 tokens. The fixture reports 12 input tokens.
Same arithmetic on the max_tokens cap: 256 output tokens ≈ 256 × 4 = 1,024 characters ≈ 193 English words at the prompt’s 5.3 characters per word. A one-sentence answer needs roughly 20–40 tokens, so the cap is generous here — and it is a cap, not a target: you are billed for the tokens the model actually produces, not for 256.
An SDK is a convenience wrapper around one HTTP POST. When the wrapper’s error is cryptic, reproducing the call by hand is the fastest way to see the status line and the response body — the two things that name the problem.
The source says it plainly: “This is what the SDKs do under the hood. Understanding the raw HTTP call helps when debugging.” Python’s standard library is enough — no package to install:
import os
import json
import urllib.request
url = "https://api.anthropic.com/v1/messages"
headers = {
"Content-Type": "application/json",
"x-api-key": os.environ["ANTHROPIC_API_KEY"],
"anthropic-version": "2023-06-01",
}
body = json.dumps({
"model": os.environ.get("LLM_MODEL", "claude-sonnet-5"),
"max_tokens": 256,
"messages": [{"role": "user", "content": "What is a neural network in one sentence?"}],
}).encode()
req = urllib.request.Request(url, data=body, headers=headers, method="POST")
with urllib.request.urlopen(req) as resp:
result = json.loads(resp.read())
print(result["content"][0]["text"])The three headers are the whole ceremony. Content-Type: application/json tells the server how to parse the body. x-api-key carries the credential — Anthropic’s API uses this header rather than the more common Authorization: Bearer, which is why the quiz question about it exists. And anthropic-version: 2023-06-01 pins the API contract to a date, so a server-side change cannot silently reshape your request or response. Note where the key is not: never in the URL. Query strings land in logs, proxies and shell history; headers are the safe place for credentials.
The response is ordinary JSON — with no SDK, it is an ordinary Python dictionary, which is exactly the point: result["content"][0]["text"] and result["usage"] are visible with no types in between. TypeScript’s equivalent is global fetch with the same three headers and await resp.json(); the source’s TypeScript port does exactly that, with a small .env loader in front and a MOCK=1 switch so the whole program runs with no network.
Reconstructing an exchange from the headers up is the debugging habit this section teaches. This is a teaching reconstruction — header order and exact bodies vary by API version — but every line here has a counterpart in the panel above:
One practical loop: when an SDK error message is too high-level, run the raw call once. The HTTP status and the JSON error body usually name the missing field or the limit that was crossed — a 400 that says max_tokens: required, a 404 that names the model string, a 429 with retry-after: 30.
HTTP answers with a three-digit code before it answers with words. Read the code and you know who has to act: your request (4xx), their server (5xx), or the clock (429, Retry-After).
The first digit carries the meaning. 4xx means the request is the problem — retrying an unchanged request will produce an unchanged error. 5xx means the provider’s side failed — the request was fine, and waiting helps. The one hybrid is 429: your traffic crossed a limit, so you must wait, but the wait is specified.
| Code | Meaning | First thing to do | Retry? |
|---|---|---|---|
| 400 | Bad request — malformed JSON or a missing required field | Print the body you sent; compare with the schema | No |
| 401 | Missing or invalid key | Check the variable name and restart the process | No |
| 403 | The key is valid but not permitted to do this | Check model access and key scopes in the console | No |
| 404 | Wrong endpoint or unknown model id | Print the exact URL and model string | No |
| 429 | Rate limit — too many requests or tokens per minute | Wait for Retry-After, then back off with jitter | Yes, after the wait |
| 500 / 503 | Server error or overload — not your request | Retry with backoff and a small cap; check the status page | Yes |
| timeout | The client gave up first (connect vs read) | Check the network; raise the read timeout or stream | Depends on where it stopped |
Exponential backoff, worked out. A 429 usually comes with a Retry-After header in seconds. When it does not, the standard policy doubles the wait each time and caps it. Start at one second, cap at eight, and stop after a few attempts:
Jitter is the part beginners skip and production systems require. If a thousand clients receive a 429 in the same second and every one waits exactly one second, they all retry together and trip the limit again — a thundering herd. Randomising each wait (full jitter picks uniformly from zero to the ceiling) spreads the retries out and halves the expected total wait, without changing the worst case. And a retry is not free: every attempt consumes rate-limit budget and tokens, so cap the number of attempts and surface the error instead of looping forever.
Streaming: the third mode. A normal call returns one response body when the whole answer is ready. A streamed call keeps the connection open and sends the answer token by token — words arrive one by one. The billing does not change (every token still counts), but the experience does: a 300-token answer generated at roughly 50 tokens per second takes about 6 seconds end-to-end, yet the first tokens appear after about 0.3–0.5 seconds (illustrative numbers). That gap between time-to-first-token and total time is what streaming hides — and it also keeps long generations from tripping a read timeout, because data keeps arriving.
One rate-limited request, three retry policies. Each circle is an attempt; the bars are the waits. A Retry-After header turns into a wall you must respect — ignore it and the retries are just more traffic.
Jitter is not decoration. If a thousand clients get a 429 at the same second and all wait exactly 1s, they retry together and trip the limit again. Randomising the wait spreads them out — the average total wait halves with full jitter.
Pick a status family, or paste the error text you actually got. Every card answers three questions in order: whose fault is it, should you retry, and what is the first thing to change.
What happened · The server did not recognize your credential: the variable was never set in this process, the name is misspelled, the value is truncated, or the key belongs to a different environment.
First fix · Check the variable name (ANTHROPIC_API_KEY), confirm the process actually inherited it (a new terminal needs the export again), and restart the program after fixing the environment.
Retry? · No. Retrying the same wrong key just repeats the 401 — fix the credential first.
The word “error” is not a diagnosis. A 401 retried a thousand times is a thousand identical failures; a 529 retried with backoff is a request that succeeds.
Your script gets a 429 with retry-after: 30. What is the right move?
A token is the unit a model actually reads and writes — and the unit you pay for. Input and output are counted separately, the context window caps their sum, and the rule of thumb for English is about four characters per token.
A token is not a word. A tokenizer (the piece of the pipeline that turns text into numbers, trained with algorithms such as byte-pair encoding, BPE) splits text into subword pieces: common words are one token, rare words split into fragments, and punctuation adds its own. That is why the same sentence can cost different amounts in different models. The practical rule of thumb, and the one this lesson uses everywhere: ≈4 characters per token in English. It is an estimate for planning — the provider’s tokenizer is the authority, and the first place to see it is the usage object on every response. Code and non-English text typically spend more tokens per character, so treat ÷4 as a floor, not a guarantee.
| Piece of text | Characters | Estimated tokens (÷4) | Rough English equivalent |
|---|---|---|---|
| The one-line question | 41 | ≈11 (the fixture bills 12) | a short sentence |
| The lesson’s 60-word prompt | 320 | ≈80 | a paragraph |
| A 300-token reply | 1,200 | 300 | ≈230 words |
| A 4,000-token document | 16,000 | 4,000 | ≈3,000 words |
| A 200,000-token context window | 800,000 | 200,000 | ≈150,000 words — a long book |
Two meters, one window. Every response reports input tokens (the prompt plus the conversation you sent) and output tokens (what the model wrote). They are billed at different rates — output is usually the more expensive meter. And there is a hard ceiling: input + output must fit inside the model’s context window. On the example 200,000-token window, max_tokens=4096 caps the answer at 4,096 tokens (2.05% of the window), leaving at most 200,000 − 4,096 = 195,904 tokens for the prompt. This lesson’s worked-example call (the 60-word prompt) — an ≈80-token prompt asking for at most 300 output tokens — uses 380 of 200,000, which is 0.19% of the window. Small talk is small; documents are not.
A worked bill, with example rates. Rates change and vary by model, so the numbers below use invented example prices — $3 per million input tokens and $15 per million output tokens — purely to show the arithmetic. Always read the provider’s live pricing page for real numbers.
Two cost controls live in the request itself. Caching: several providers can cache a repeated prefix — a long system prompt, a document you ask about in several calls — and bill that prefix at a reduced rate; the discount and the rules differ, so check the pricing page. Retry discipline: a retried call is a billed call, and a messages request is not idempotent, so a blind retry can pay twice for two answers. That is the same discipline the last chapter built: retry only what waiting can fix (429, 5xx), with backoff and a cap.
Type a prompt and a reply length. The estimate is the lesson’s rule of thumb — characters ÷ 4 for English — not a tokenizer. The rates are examples for arithmetic; the live prices live on the provider’s pricing page.
80 input + 300 max output = 380 tokens · 0.19% of the example window.
These rates are examples, not today’s prices. Token counts themselves are estimates too: the provider’s tokenizer is the authority, and code or non-English text usually spends more tokens per character. See live pricing ↗
With the example rates ($3 per million input, $15 per million output), which costs more: 2,000 input tokens of a document sent once, or a 300-token answer?
Answer before you look. The key-hygiene question and the rate-limit question are the two that separate “I read the chapter” from “I could debug this at 2 a.m. with a 401 in one hand and a 429 in the other”.
0 / 5 answered · 0 correct
01What is an API key used for when calling an LLM service?
02Why should API keys never be hardcoded directly in source code?
03What is the recommended way to store API keys for local development?
04In the raw HTTP API call to Anthropic, which header carries the API key?
05What happens when you exceed an API's rate limit?
Click a card to swap the lazy description for what it actually means.
Four problems with exact numbers — make the first call, compare the raw HTTP and SDK shapes, read a wrong-key error like an engineer, and write the rotation plan for a repo that leaked. Try first; a worked answer is one click away.
Export the variable (masked here — the real value never appears in a lesson): `export ANTHROPIC_API_KEY=sk-ant-…`, then run the lesson's first_api_call.py. Expected output shape: one sentence of answer, then `Tokens used: 12 in, 28 out` for the source's fixture. The fresh-terminal repeat fails differently depending on where the key was missing: with no value at all the SDK client raises before any network call — a local configuration error, not a 401 — because Anthropic() refuses to construct without a key. If the key is present but wrong, the request goes out and the server answers 401 with an authentication_error body. Both are fixed the same way: put the export in the shell you actually run the program from (or load the .env), then restart the process. Numbers to notice: the prompt 'What is a neural network in one sentence?' is 41 characters ≈ 11 estimated tokens and the fixture bills 12 — the ÷4 rule is planning, the usage object is billing.
The raw call returns plain Python dicts: `result["content"][0]["text"]` and `result["usage"]["input_tokens"]`. The SDK returns typed objects: `response.content[0].text` and `response.usage.input_tokens` — same JSON underneath, friendlier names on top. Three things the SDK handled: (1) it set exactly the three headers (Content-Type: application/json, x-api-key, anthropic-version: 2023-06-01) and JSON-encoded the body; (2) it retries some failures (429/5xx and connection errors) with backoff, so a transient error may never reach your code; (3) it raises typed errors that carry the status and the response body, and exposes streaming helpers. The comparison also shows the debugging move: when the SDK's message is cryptic, run the raw call once and read the status line and error body yourself.
With a wrong-but-present key the server answers HTTP 401 and a body shaped like `{"type":"error","error":{"type":"authentication_error","message":"invalid x-api-key"}}`; the Python SDK surfaces it as its authentication error type carrying the same body. Classification: 401 is a 4xx, so it is your request's fault and retrying changes nothing — a thousand retries are a thousand identical failures. The fix is credential custody, not code: confirm the variable name (ANTHROPIC_API_KEY, not ANTHROPIC_KEY or ANTHROPIC_API_TOKEN), confirm the shell that runs the process actually inherited it, confirm the value was not truncated by a stray newline in the .env, then restart the process because environment variables are read at client construction. With an empty value the failure happens even earlier, locally, when Anthropic() is constructed — a useful distinction: no key is a configuration error, a wrong key is a server 401.
1 · Revoke the key in the provider console. This is the only step that ends the exposure: the old string stops working immediately, whatever copies exist anywhere. 2 · Create a replacement and update every consumer — the shell profile, the .env, CI secrets, deployed services — so the work continues. 3 · Restart the processes that cached the old value; a running process never re-reads the environment. 4 · Audit the usage and billing dashboards for requests you did not make, and note the time window for the incident. 5 · Clean up the repository: add .env to .gitignore, purge the blob from history with git filter-repo or BFG, force-push, and tell collaborators to re-clone — this fixes the future of the repo, not the past of the key. 6 · Prevent the repeat: a pre-commit secret scanner (gitleaks, trufflehog) plus the same scanners in CI, and a .env.example that documents the variable names without values. What each step does not fix: steps 5 and 6 never restore the old key's secrecy, and step 1 alone does not clean the history — the plan is ordered because ending the exposure comes before tidying up.
You do not need to master these here. Each one gets a proper treatment in its own lesson; the one-line meaning is enough to keep reading. Orange dotted underlines in the prose point back to this list.
This lesson is a port of an open course. Everything here traces back to it — and the next step is running the code yourself.
Lesson text adapted from AI Engineering from Scratch (Phase 00, Lesson 04) and the Math Foundations Notebook reference build. The five labs (the request-lifecycle animator, the secret-leak scanner, the 429 backoff timeline, the token-and-cost calculator and the error triage board) are original to this page, as are the second worked numeric examples: the token arithmetic behind the ÷4 rule (the 60-word, 320-character = 80-token prompt; the 800,000-character ≈ 150,000-word context window; the 16,000-character document; 256 output tokens ≈ 1,024 characters), the worked bills at clearly-labelled example rates, the backoff arithmetic (1 + 2 + 4 + 8 = 15s, 7.5s expected with full jitter, 11.25s with equal jitter, Retry-After 30 dominating every ceiling at 4 × 30 = 120s), the context-window subtraction (200,000 − 4,096 = 195,904 input tokens), the streaming latency numbers, the agent-cost framing, the memory hooks and the rotation checklist. Everything ported — the four-part pattern, key hygiene, both SDK snippets, the raw HTTP call, the status taxonomy and the quiz — traces back to the source. Every rate in this lesson is an invented example for arithmetic; today's prices live on the provider's live pricing page, never here.