API & Networking Basic
When an internal API call goes wrong, you usually see the stack trace right away.
An API that receives data from external systems is harder: the sender has its own retry policy, the response can get lost on the way back, and anyone who knows the URL can send fake JSON.
This page is the starting point for picking the right article. The full list is in the left-hand menu.
Pick an article by question
Section titled “Pick an article by question”| Question | Article |
|---|---|
| Receiving requests from outside: can you trust them, are duplicates handled? | Webhooks: signature, retry, idempotency |
| How should an API report errors so clients can branch on them? | API errors with RFC 9457 |
| How much time is left for a request that crosses several hops? | Timeout budget and deadline |
| One client sends too many requests: how to block it, which error to return? | Rate limiting for APIs |
A client retries POST /orders after a timeout: how do you avoid creating two orders? |
Idempotency-Key |
| Static assets and API responses behind a CDN: how long to cache, how to revalidate, what must never be cached? | HTTP caching |
Webhooks
Section titled “Webhooks”Separates three mechanisms that often get lumped together (signature, idempotency, ACK), with a sample verify-then-dedupe handler and a crash-point table. The key point: verify against the raw body before parsing.
API errors
Section titled “API errors”The HTTP status states the class of outcome, type is a stable error-type code, and detail is for human readers. Includes JSON examples contrasting 200 {success:false} with 409 problem+json, plus a status table and retry guidance.
A timeout bounds one step; a deadline bounds the whole request. Includes an 800 ms waterfall, a timeout hierarchy table and how to chain AbortSignal in Node.
Rate limiting
Section titled “Rate limiting”Choosing an algorithm (fixed window, sliding window, token bucket), storing state in Redis with atomic Lua, and returning 429 with Retry-After. Includes a demo that runs the same burst through two algorithms.
Related
Section titled “Related”Retries and uncertain state: the eight fallacies of distributed computing and retry, backoff, jitter. Handling duplicates on the message side: idempotent consumer and transactional outbox. The authentication boundary in the browser: CORS and CSRF.