1 Headers That Matter Most
Headers carry metadata about a request or response. A request can have a correct body and URL and still fail because a required header is missing — which is exactly why headers deserve close attention, not a quick skim.
application/json is most common, but you'll also meet application/x-www-form-urlencoded (frequent at OAuth token endpoints and older web apps, e.g. grant_type=client_credentials&client_id=myclient&client_secret=secret), application/xml, multipart/form-data, and application/octet-stream. A very common failure: the client sends JSON when the API expects form-encoded data — the values are correct, but the encoding is wrong, and the request fails anyway.Accept: application/json. Some older APIs support Accept: application/xml too, and a server can support multiple formats at once.Authorization: Bearer eyJhbGciOi... or Authorization: Basic dXNlcjpwYXNzd29yZA==. The security implications of these two are very different (Lesson 3 covers both in depth).2 Other Headers & Correlation IDs
Depending on the environment you'll also meet Host, Origin, Referer, User-Agent, Cookie/Set-Cookie, Cache-Control, Content-Length, Content-Encoding, Accept-Encoding, Accept-Language, Location, Retry-After, ETag, If-None-Match, X-Forwarded-For, X-Request-ID, X-Correlation-ID, and Traceparent. Some organisations add custom headers like X-API-Key, X-Customer-ID, X-Tenant-ID, or X-Transaction-ID — header names starting with X- have historically been the convention for custom headers, though modern designs don't require it.
Correlation IDs are especially valuable in enterprise troubleshooting. Imagine Mobile App → API Gateway → Authentication Service → User Service → Database — one user request crosses several systems, each generating thousands of log entries a minute. A correlation ID like X-Correlation-ID: 8f65e820-1a62-4f58-a78c-a18c86135ce8 lets you search each system's logs for that exact value and follow one transaction across all of them, instead of trying to match entries by timestamp and guesswork.
3 Query Parameters, Path Parameters & URL Encoding
API URLs often carry query parameters: https://api.example.com/users?enabled=true, with multiple parameters joined by & — /users?enabled=true&department=security&limit=100.
Compare that to a path parameter: in /users/12345, 12345 identifies one specific resource, while /users?department=security filters a collection. API documentation typically writes path parameters as /users/{userId}, where the braces mean the value varies (/users/123, /users/456...).
Special characters sometimes need URL encoding — a space might appear as %20, @ as %40, : as %3A, / as %2F. Improper encoding causes strange authentication and parameter problems, and matters especially with passwords, redirect URLs, OAuth parameters, search parameters, Base64 values, certificates, and international characters.
4 Status Code Categories & Success (2xx)
HTTP status codes are among the most important troubleshooting signals in IT, grouped into five categories: 1xx Informational, 2xx Success, 3xx Redirection, 4xx Client-related errors, 5xx Server-related errors. Exact interpretation still depends on the specific API.
GET /users/123 returning 200.POST /users.POST /reports returning 202 while the report generates later.5 400 & 401: Bad Requests and Authentication
400 Bad Request usually means the server couldn't process the request because something about it was invalid — invalid JSON, a missing required parameter, incorrect parameter format, unsupported value, wrong data type, invalid syntax, or bad encoding. Expecting {"enabled": true} and receiving {"enabled": "banana"} is a classic 400.
401 Unauthorized, despite its name, generally indicates an authentication problem — think "the server doesn't accept my authentication," not "you're not allowed." Possible causes: a missing access token, an expired or invalid token, an incorrect API key, wrong username/password, the wrong OAuth client, a token issued by the wrong identity provider, an incorrect signature, a token not yet valid, an incorrect audience, or failed certificate authentication. You'll often see WWW-Authenticate: Bearer alongside a 401.
🔮 Predict first
You get a 401. List, in order, the five or six things you'd check before assuming the credentials themselves are wrong.
Reveal a working checklist
Was an Authorization header actually sent at all? Is the token expired — check its exp claim against the current time? Is the token even meant for this API (a token for graph.microsoft.com won't work against mycompany-api.example.com)? Is the aud (audience) correct? Is the iss (issuer) trusted? Is the token signed with a key the API actually trusts? And is the system clock correct on both sides — clock skew alone can break exp, nbf and iat checks even with a perfectly valid token. Lesson 3 goes deep on every one of these.
6 403 & 404
403 Forbidden normally means the server understood the request but refuses to allow it: 401 = "who are you / your authentication is unacceptable." 403 = "I know enough about you, but you can't do this." Causes include missing permission, a missing OAuth scope, a missing role, a restricted account, a blocking Conditional Access policy, a disallowed IP, an API gateway or WAF policy denial, or a tenant-level restriction. E.g. a token carrying scope: users.read attempting DELETE /users/100 (which needs users.delete) gets a 403.
404 Not Found normally means the requested resource couldn't be found — an incorrect endpoint, wrong resource ID, incorrect API version or hostname, wrong path, a deleted resource, a routing problem, or an API gateway misconfiguration. Security-conscious APIs sometimes deliberately return 404 rather than 403 for resources a caller shouldn't even know exist — so a 404 doesn't always prove a resource genuinely doesn't exist.
7 The 401 vs 403 vs 404 Model, and Other 4xx
Memorise this troubleshooting model:
| Code | First thought | Then check |
|---|---|---|
| 401 | Authentication | Token presence, expiry, issuer, audience, signature |
| 403 | Authorization (auth probably worked) | Roles, scopes, permissions, policies |
| 404 | Resource / path | Endpoint, URL, API version, resource ID |
Don't treat this as an absolute rule — APIs sometimes implement status codes poorly, so logs remain essential. A few other 4xx codes worth recognising: 405 Method Not Allowed (you sent POST to an endpoint that only supports GET/PATCH/DELETE); 409 Conflict (e.g. trying to create a username that already exists); 415 Unsupported Media Type (often a Content-Type mismatch — the API expects application/json but got text/plain); 422 Unprocessable Content (valid syntax, but the supplied information can't be processed, e.g. "dateOfBirth": "banana"); 429 Too Many Requests (a rate limit was exceeded — the response may carry Retry-After: 60, telling you how long to wait).
8 Server Errors: 500, 502, 503, 504
Client → Load Balancer → API Gateway → Application, if the gateway can't get a valid response from the application, it returns 502 — the gateway itself may be perfectly healthy.Lesson Outcome
You should now be able to explain what Content-Type, Accept and Authorization each do and why a correlation ID matters, distinguish query parameters from path parameters, and diagnose 400/401/403/404/429/500/502/503/504 using the right first questions for each. Lesson 3 goes deep on exactly what should be inside that Authorization header — every major API authentication mechanism you'll encounter.