Jan Mikoláš
Glossary
HTTP status code
A status code describes the HTTP outcome of a request, not the entire story of a business process. “Accepted for asynchronous processing” and “the order has been delivered” are different pieces of information.
Short definition
A short, standardised signal about what the server did with a request.
An HTTP response begins with a status code from 100 to 599. The first digit identifies the class: informational 1xx, successful 2xx, redirection 3xx, client error 4xx and server error 5xx. Together with the method, headers and response body, the specific code tells the client whether to use the result, correct the input, sign in, follow a redirect or handle a temporary error.
The correct status is not decoration for monitoring. It changes the behaviour of browsers, HTTP clients, caches and retry mechanisms. Returning 200 with an error hidden in JSON complicates both automated clients and observability. It is equally inaccurate to return 500 for invalid input the client can correct, or 404 for denied access unless this is a deliberate measure to avoid revealing the existence of a resource.
What it is used for
Clear results for websites, APIs and integrations
A code is selected according to the result of the specific HTTP request, not from a list of favourite numbers.
- successfully reading or changing a resource in an administration interface and API
- reporting the creation of a new resource together with its Location
- asynchronous acceptance of an import or export that a worker will complete
- distinguishing invalid input, missing authentication, insufficient permissions and a state conflict
- monitoring availability, upstream failures and controlled retries by an integration client
Practical example
Asynchronous catalogue import
A partner submits a catalogue that will take several minutes to validate and process. After basic validation, the API creates a job and returns 202 Accepted with the job resource in the Location header. The client knows the request was accepted but must not yet claim that the catalogue is complete.
If the JSON is syntactically invalid, the API returns 400. If the JSON is valid but contains a nonexistent currency or violates a catalogue rule, the contract can return 422 and identify the affected field in a structured way. The client can correct both situations, so neither is a 500.
HTTP/1.1 202 Accepted
Location: /api/import-jobs/imp_42
Content-Type: application/json
{"id":"imp_42","status":"queued"}
HTTP/1.1 422 Unprocessable Content
Content-Type: application/json
{"code":"invalid_currency","field":"items[0].currency"}How it works
From the outcome of an application step to the client response
The status summarises the HTTP outcome; details for a person or program belong in a stable response body.
- The request reaches the application The application determines whether the method and path exist and verifies identity, permissions and input data.
- A specific outcome is evaluated A resource may be created, asynchronous work accepted, validation may fail or a dependent server may be unavailable.
- A status and metadata are selected The server may add Location after creation, WWW-Authenticate when sign-in is required or Retry-After for a controlled delay.
- The response carries details JSON or HTML explains a safe level of error detail. Internal stack traces, SQL and secrets do not belong in a public response.
- The client responds according to the contract It displays an error, refreshes authentication, follows a redirect, schedules a retry or continues with the received representation.
Main parts and concepts
The code class is only the beginning; the specific semantics matter.
Several codes recur in APIs, and confusing them gives the client the wrong instructions.
2xx success
200 usually returns a representation. 201 means that a resource was created and commonly includes Location. 202 says that a request was accepted for further processing, not that the work has finished. 204 confirms success without a response body.
3xx redirection
A redirect instructs the client to take another step according to Location. The code is selected with the method and expected preservation or change of the request in mind; it is not a substitute for returning an incorrect URL in JSON.
Authentication and permissions
401 means the request lacks valid authentication credentials and can include WWW-Authenticate. 403 means the server understood the request but refused to authorize it. A contract can deliberately use 404 when it must not reveal the existence of a sensitive resource.
Input and conflicts
400 is used for an invalid request at the HTTP level or generally invalid input under the contract. 409 identifies a conflict with the current state of a resource. 422 can describe an understandable request whose instructions cannot be processed because of semantic validation.
Server errors and retries
5xx signals that the client sent an apparently valid request but the server could not fulfil it. Retries are not governed by the 5xx class alone: the method, idempotency, timeout and service instructions all matter.
Benefits and limitations
A short standard code needs to be supplemented with specific details.
Benefits
- standard behaviour for browsers, HTTP clients, caches and monitoring
- better distinction between client errors and infrastructure failures
- the ability to control resource creation, redirects and asynchronous work acceptance safely
- clearer metrics and alerts without parsing free-form JSON text
Limitations and common mistakes
- returning 200 with an error object instead of the appropriate 4xx or 5xx
- presenting 202 as a completed asynchronous process
- using 401 and 403 interchangeably without authentication context
- retrying every 5xx response for a non-idempotent write
- overly detailed error messages that reveal internal data or the existence of a resource
When it makes sense
Whenever an HTTP response needs to be machine-readable.
Every HTTP response has a status code, but its meaning is designed at the endpoint and documented contract level. An online store can return 201 when creating an order, 202 when accepting a long import and 409 for an order version conflict. A stable JSON structure then provides the details of the specific problem rather than an arbitrary translation of text.
A code alone does not describe the complete business state. Order processing may be technically accepted with 202 and later fail. The API therefore usually returns an identifier for a job or resource where the client can obtain the state. That is more accurate than pretending that 200 means success merely because the HTTP connection worked.
What to consider
Choose the code according to the request outcome and test it as a contract.
Consistency does not mean every endpoint uses the same code; it means that the same situation has the same meaning.
- return 201 and, where appropriate, Location for a created resource, and 202 for accepted long-running work
- distinguish missing or invalid authentication, insufficient permissions, validation and a state conflict
- keep the public error body stable, safe and useful to the client
- evaluate the idempotency of the operation rather than only the status code before retrying
- include statuses and key headers in integration tests, monitoring and API documentation
Common questions
How to interpret API results
What is the difference between 200, 201 and 204?
200 usually returns a successful representation. 201 says a new resource was created, often with Location. 204 confirms success but has no response body.
What is the difference between 401 and 403?
401 means missing or invalid authentication. 403 means the server recognised the identity but did not permit the specific action.
Does 202 mean the import has completed?
No. It means the server accepted the request for further processing. The client should obtain the status from a job or another documented resource.
Can I retry a request after every 500 response?
Not automatically. You need to know the operation's idempotency, any idempotency key and the retry rules. Otherwise an order may be created or a payment sent twice.
How I work with APIs in practice
I design API responses for clients, operations and safe retries.
In integration services, I address statuses, error contracts, asynchronous processing and idempotency so that a request outcome does not mislead a user or another system.