What is the X-Request-Id header and why should I always capture it?

X-Request-Id is a unique identifier assigned to each API request, either by the client or the API gateway. It allows you to trace a single request through load balancers, microservices, and log aggregation systems. When reporting an issue to an API provider, the request ID lets their support team find exactly what happened in their logs. Always log this header in your client and propagate it through downstream service calls.

How do I read rate limit headers to avoid getting 429 errors?

Check three headers on every response: X-RateLimit-Limit (total allowed requests per window), X-RateLimit-Remaining (how many you have left), and X-RateLimit-Reset (Unix timestamp when the window resets). When X-RateLimit-Remaining approaches zero, slow down your request rate or pause until the reset time. If you do get a 429, use the Retry-After header to know exactly how long to wait.

Why am I getting an HTML error page from my JSON API?

If the response Content-Type is text/html instead of application/json, your request likely hit a proxy, load balancer, or web server error page rather than the API itself. Common causes: the API is down and the reverse proxy returns its default error page, the URL is wrong and hits a web server instead of the API, or a WAF/CDN blocked the request and returned its own HTML response page. Check the HTML content for clues about which layer generated it.

What does the WWW-Authenticate header tell me when I get a 401?

The WWW-Authenticate header specifies which authentication scheme the server expects (Bearer, Basic, etc.) and may include error details like 'error=invalid_token' and 'error_description=The token has expired'. This tells you whether to refresh your token, re-authenticate entirely, or switch auth methods. Without reading this header, you're guessing at the cause of the 401.

How do I check if caching is causing stale API data?

Inspect the Cache-Control response header for directives like max-age (how long the browser caches without revalidating) and no-store (no caching at all). Check the Age header to see how long a CDN has held the cached response. Look for ETag values and verify your client sends If-None-Match on subsequent requests. If you see 304 Not Modified responses, the cache is active. To bypass caching during debugging, add a Cache-Control: no-cache request header or append a unique query parameter.

Analyzing API Headers for Troubleshooting