# HTTP Status Code

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

- Type: term
- Domain: Engineering & architecture
- Level: Foundational
- Last reviewed: 2026-09-23
- Original: [Soroush’s Product Wiki](<https://wiki.soroush.uk/topic/http-status-code/>)

## What 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.

## Why 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.

## When 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.

## How 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.

## A practical 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.

## Where 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.

## Visualization

[View the visualization on the website](<https://wiki.soroush.uk/topic/http-status-code/#visualization-http-status-code>)

## Sources

1. [HTTP Semantics: Status Codes](<https://www.rfc-editor.org/rfc/rfc9110#name-status-codes>) — RFC Editor · Internet Standard
2. [HTTP Response Status Codes](<https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status>) — MDN Web Docs · Official technical documentation

## Related topics

- [HTTP](<https://wiki.soroush.uk/topic/http/>)
- [HTTP Method](<https://wiki.soroush.uk/topic/http-method/>)
- [Request and Response](<https://wiki.soroush.uk/topic/request-and-response/>)
