HTTP Status Codes and What They Really Mean
When the Markdown Link Checker follows a URL, the first meaningful response it receives is an HTTP status code. These three-digit numbers tell the story of what happened during the request. Understanding their meaning helps explain why certain links are flagged as healthy, suspicious, or broken.
Status codes in the two hundreds generally indicate success. A two hundred OK means the server delivered the requested resource without issue. Two hundred one Created and two hundred four No Content are rare in documentation links but still count as healthy since they confirm the target exists.
Redirection Family
Codes in the three hundreds signal redirection. Three hundred one Moved Permanently and three hundred eight Permanent Redirect indicate the resource has a new canonical location. The checker follows these automatically and reports the final destination. Three hundred two Found and three hundred seven Temporary Redirect are treated more cautiously since they imply the move may not be permanent. Long redirect chains or loops are flagged as warnings because they slow down page loads and confuse crawlers.
Client Error Responses
Four hundred series codes almost always indicate a problem. Four hundred Bad Request is uncommon for simple GET requests but suggests malformed URLs. The infamous four hundred four Not Found means the resource does not exist at that address. Four hundred three Forbidden and four hundred one Unauthorized point to access restrictions. Four hundred twenty-nine Too Many Requests signals rate limiting, which the tool respects by backing off before retrying.
Server Error Responses
Five hundred codes reflect server-side trouble. Five hundred Internal Server Error is generic but serious. Five hundred three Service Unavailable often appears during maintenance or overload. Five hundred four Gateway Timeout means an intermediate proxy or load balancer gave up waiting for a response. All five hundred responses are treated as errors because they indicate the target is currently unreachable regardless of the URL syntax.
The checker classifies outcomes into three buckets. Success includes two hundreds and properly resolved three hundreds. Warnings cover soft failures such as temporary redirects, rate limits, or suspicious final destinations. Errors include four hundreds, five hundreds, timeouts, DNS failures, and SSL issues. This clear categorization helps maintainers quickly understand the severity of problems in their documentation.
Knowing what each status really means turns raw numbers into actionable insight. Instead of blindly trusting a link because it once worked, teams can now see exactly where maintenance is needed.
The upcoming article dives into how redirects are followed and how final URLs are resolved.