HTTP Request Builder

HTTP requests in 2026 — methods, headers, status codes, and the API patterns that ship

HTTP is the protocol layer every networked product runs on. Even when you are calling a "GraphQL API", a "gRPC service", or a "WebSocket endpoint", you are still riding HTTP/1.1, HTTP/2, or HTTP/3 underneath. Knowing the protocol cold pays off in every debugging session — every "why does this work in Postman but not in my code?" question, every CORS preflight mystery, every 401-when-it-should-be-403, every cached-response surprise. This guide is the working reference for the protocol fundamentals (RFC 9110), the headers that actually matter, the auth schemes that secure modern APIs, and the cURL → code patterns that live in every backend codebase.

HTTP methods — what each one is for, and what's idempotent

"Safe" means the request should not change server state. "Idempotent" means N identical requests have the same effect as one. These properties drive practical decisions:

• Retry policies: safe to auto-retry GET, HEAD, PUT, DELETE on network errors. Don't auto-retry POST without an idempotency key.
• Caching: only safe methods can be cached. GET is the workhorse here.
• CSRF protection: only state-changing methods (POST, PUT, PATCH, DELETE) need CSRF tokens.

The headers you actually need to know

Status code groups — which ones mean what

Two distinctions every junior dev gets wrong:

• 401 vs 403: 401 means "you didn't authenticate" (no/invalid token); 403 means "you authenticated but you can't access this".
• 302 vs 307 vs 308: 302 historically allowed clients to change POST→GET on redirect; 307/308 explicitly preserve the method. Use 308 for permanent redirects of POST endpoints.

Authentication schemes — JWT, OAuth, API key, HMAC, mTLS

Picking auth correctly the first time saves a rewrite later. For browser-facing APIs, Bearer JWTs (issued via OAuth 2.0 PKCE) are the modern default — short-lived access tokens with refresh tokens stored in HttpOnly cookies. For server-to-server, API keys with rotation or HMAC request-signing are simpler. To inspect or mint a Bearer token while you're testing here, the JWT decoder shows the payload claims and the JWT generator mints signed test tokens with HS256/RS256/ES256.

CORS — the browser policy that confuses everyone

The Same-Origin Policy stops a page on evil.com from reading responses from bank.com. CORS is the carve-out: a server can opt-in to allow specific cross-origin requests. The flow:

1. Simple requests (GET/HEAD/POST with simple Content-Type) — browser sends the request directly. Server responds with Access-Control-Allow-Origin: <origin> or *.
2. Preflighted requests (PUT, DELETE, custom headers, JSON body) — browser sends an OPTIONS preflight first. Server must respond with Access-Control-Allow-Methods, Access-Control-Allow-Headers, and Access-Control-Allow-Origin.
3. Credentialed requests (cookies, Authorization header, client certs) — server must respond with Access-Control-Allow-Credentials: true AND a specific origin (not *).

The single biggest debugging tip: CORS errors only happen in browsers. The same request from cURL, Postman, or your Node backend works fine. If your browser request fails but cURL succeeds, it's CORS — fix the server.

cURL — the lingua franca of API debugging

The cURL output is the de-facto sharing format. Common flags:

curl -X POST https://api.example.com/users \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"email":"alice@example.com","name":"Alice"}' \
  -i        # include response headers
  -v        # verbose: show request & response in detail
  -L        # follow redirects
  -s        # silent (no progress bar)
  -w "%{http_code}\n"   # write out specific values
  --fail-with-body      # exit non-zero on 4xx/5xx but still print body
  --resolve api.example.com:443:127.0.0.1   # bypass DNS for local testing

HTTP/1.1 vs HTTP/2 vs HTTP/3 — what changes

• HTTP/1.1 (1997): Text protocol. One in-flight request per connection (or pipelining, which never worked reliably). Requires multiple TCP connections to parallelize.
• HTTP/2 (2015): Binary, multiplexed. Multiple streams over a single TLS connection. Header compression (HPACK). Server push (deprecated 2022).
• HTTP/3 (2022): Built on QUIC over UDP instead of TCP. No head-of-line blocking. Faster connection setup. Production-ready in Cloudflare, Akamai, Fastly, Google.

For most APIs, HTTP/2 is the default, HTTP/3 is the upgrade path. From the application code's perspective the API is identical — you write fetch() or requests.get() the same way. Performance differences show up in p99 latency and concurrent-request scenarios.

Idempotency keys — the pattern that makes retries safe

Stripe, Square, Adyen, Paddle, and every modern payments API support idempotency keys. The client sends a unique key with the POST; the server stores the response keyed by that key. If the client retries (because the network dropped, or the server timed out), the server returns the cached response instead of double-charging. The pattern:

POST /charges HTTP/1.1
Idempotency-Key: 09cb3b3f-6e7f-4bba-8a4d-5d07c5b2c91a
Content-Type: application/json

{"amount": 1000, "currency": "usd"}

Use a UUID v4 generated once per logical operation. Don't reuse a key across distinct operations or you'll get the cached response from the previous one.

Common HTTP-request mistakes

• Putting API keys in query strings. Leaks into server logs, browser history, and Referer headers. Use the Authorization header.
• Not setting Content-Type on POST/PUT. Server can't parse the body. application/json is the right answer 95% of the time.
• Treating 200 as success and everything else as failure. 201, 202, 204 are also success. Check 2xx generally.
• Not handling 429 (rate limit). Servers return Retry-After in the response — wait that long before retrying.
• Auto-retrying POST without idempotency key. You can charge a customer twice.
• Forgetting to follow redirects. 3xx responses need to be followed; some clients don't by default.
• Using cookies on a third-party API. Modern browsers reject third-party cookies by default. Use Authorization headers.
• Confusing application/json with application/x-www-form-urlencoded. Different body formats; the server cares which.
• Sending the body as a string when the server expects JSON. Stringify with JSON.stringify() in JS, but make sure the receiver parses it.
• Pasting curl from DevTools without removing cookies/auth. Right-click → "Copy as cURL" includes session cookies that expire — strip them or replace with explicit auth headers before sharing.