termEngineering & architecture

HTTP Status Code

A three-digit response code that communicates the standardized outcome class and handling semantics of an HTTP request.

Download Markdown (.md)

01What it means

An HTTP status code is a three-digit code in a response that describes the result of handling a request. The first digit groups codes into informational 1xx, successful 2xx, redirection 3xx, client-error 4xx, and server-error 5xx classes; individual codes provide more specific protocol meaning.[1][2]

Five response outcome classes The first digit gives the class; the full code gives protocol meaning
  1. 1xx · InformationalRequest processing is continuing
  2. 2xx · SuccessfulRequest was successfully received, understood, and accepted
  3. 3xx · RedirectionFurther action is needed to complete the request
  4. 4xx · Client errorRequest cannot be fulfilled as sent or authorized
  5. 5xx · Server errorServer failed to fulfill an apparently valid request

Select a registered code and pair it with required headers and a safe actionable body where clients need more detail.

02Why it matters

Clients, browsers, caches, gateways, monitors, and retry policies use status codes to decide what happened and what to do next. Accurate codes improve interoperability, debugging, reliability, analytics, and the user experience of errors.

03When to use it

Return the most specific standard code whose semantics match the HTTP outcome, supplemented by an application error body when useful. Do not create private codes when a standard code works, and do not expect a status code alone to express every business detail.

04How it works

  1. Determine whether the request is complete, successful, redirected, invalid or unauthorized, or failed at the server.
  2. Choose a registered status code that accurately represents the protocol-level outcome.
  3. Include required or useful headers, such as Location, Allow, WWW-Authenticate, or Retry-After.
  4. Provide a safe structured error body with actionable detail when clients need more context.
  5. Test how clients, caches, gateways, monitoring, and retry policies interpret the response.

05A practical example

Example

An API returns 201 Created with a Location header after creating an order, 400 for malformed input, 409 when the requested transition conflicts with current state, and 503 with Retry-After when a temporary dependency outage prevents processing.

06Where it breaks

Status codes express HTTP handling, not the full business result or root cause. Some situations plausibly map to several codes, intermediaries can generate responses, and clients must tolerate unfamiliar codes by using their class semantics.

Common mistakes

  • Returning 200 OK for every result and hiding failures only inside the response body.
  • Using 500 for client input, authentication, authorization, or state-conflict errors.
  • Choosing a code by its reason phrase without checking its normative semantics.
  • Automatically retrying every 5xx response without limits, delay, or operation-safety checks.

07Sources

  1. HTTP Semantics: Status CodesRFC Editor · Internet StandardHTTP Semantics: Status Codes
  2. HTTP Response Status CodesMDN Web Docs · Official technical documentationHTTP Response Status Codes
View saved topics

Start typing to search titles, definitions, categories, and frameworks.