Hypertext Transfer Protocol Status Codes in Application Programming Interfaces and Gateways: A Review of Standards and Practice

Every response on the web carries a three-digit status code, and in application programming interfaces that number is read far more often by software than by people. Monitoring systems, caches, retry policies, circuit breakers and gateways all act on it, so a wrongly chosen code causes failures well beyond the application that sent it. This article reviews the status code system from the point of view of the developers and architects who build and operate such interfaces. It covers the current standard and the official registry, which held 64 entries in October 2026; the meaning of each of the five classes; the accompanying headers and the standard error format; and the way status codes are produced by application frameworks and gateways, which the standards largely leave to vendors. The review draws on the standards documents, on the published documentation of widely used gateways and cloud platforms, and on a case study in which every status code discussed was produced and checked by automated tests in a reference implementation built with a current Java framework. The case study shows that the framework omits headers required by the standard in two situations, and that validation and rate-limiting errors need explicit configuration to produce the recommended codes. Widely used gateways also depart from the standard's recommendations, for example by answering a missing credential with 403 rather than 401. The article closes with a catalogue of recurring mistakes and a four-question procedure for choosing a status code.