HTTP status codes describe the response contract

Sun, 14 Jun 2026 00:00:00 +0000

A status code tells a client how to interpret this HTTP response in the context of the request method. The first digit narrows the class, but it does not establish the whole business outcome. In particular, accepted work can still be pending, and a 3xx response need not mean that a page moved. Choose the specific status and accompanying headers that match what the server has actually done.

Success has several meanings

200 indicates that the request succeeded according to the method’s semantics. A successful GET of a job-status resource can truthfully return a representation saying that the job is pending. That does not mean the job itself completed. 201 indicates creation of one or more resources, with Location identifying the primary created resource when supplied. Document which resource the client should subsequently use.

202 means the request was accepted for processing but processing has not completed. It is intentionally noncommittal about eventual execution. Provide a way to inspect progress and define terminal outcomes; otherwise the client has no reliable way to distinguish slow work from lost work. 204 means successful fulfillment with no response content. Do not attach a JSON body merely because the application normally serializes every response.

Redirection includes conditional reuse

301 and 308 describe permanent redirection, while 302 and 307 describe temporary redirection with different method-preservation rules. A 303 can direct the caller to retrieve another resource after a processing step. Select the code deliberately when a request has content or side effects; a method-changing redirect and a method-preserving one are not interchangeable.

304 is different: it answers a conditional GET or HEAD by indicating that the selected representation need not be transferred again. The recipient uses its suitable stored representation and updates cache metadata according to the caching rules. A 304 has no response content and is not an instruction to navigate to a Location. An empty displayed body is expected, not evidence that the origin lost the file.

When it breaks

Reducing every 4xx to “never retry” mishandles cases such as rate limiting. Reducing every 5xx to “retry immediately” can duplicate a non-idempotent operation or amplify overload. 503 covers temporary service unavailability, including overload or maintenance; it is not reserved for a planned maintenance window. Retry behavior also depends on the method, server guidance, and the caller’s retry budget.

404 does not promise that absence is temporary. It can mean no current representation was found or that the server is unwilling to disclose one. 410 conveys likely permanent unavailability. Likewise, 403 does not universally prove that the caller was authenticated. Avoid encoding stronger business assumptions than the status actually provides, and keep the documented response body consistent with the endpoint’s contract.

Check it quickly

Save this as status-contract.py and run python3 status-contract.py. The fixture uses real loopback HTTP requests, a tiny in-memory job state, and a fixed asset. Python’s HTTP client does not automatically follow the response Location or implement a cache here, so each next action is explicit in the script.

from http.client import HTTPConnection
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from threading import Thread
import json

job = {'state': 'absent'}


class Handler(BaseHTTPRequestHandler):
 def reply(self, status, data=b'', headers=None):
 self.send_response(status)
 if status not in (204, 304):
 self.send_header('Content-Length', str(len(data)))
 for key, value in (headers or {}).items():
 self.send_header(key, value)
 self.end_headers()
 if status not in (204, 304):
 self.wfile.write(data)

 def do_POST(self):
 if self.path != '/jobs':
 self.reply(404)
 return
 job['state'] = 'pending'
 self.reply(202, b'{"state":"pending"}',
 {'Content-Type': 'application/json', 'Location': '/jobs/42'})

 def do_GET(self):
 if self.path == '/jobs/42':
 if job['state'] == 'complete':
 self.reply(303, headers={'Location': '/results/42'})
 elif job['state'] == 'pending':
 self.reply(200, b'{"state":"pending"}', {'Content-Type': 'application/json'})
 else:
 self.reply(404)
 elif self.path == '/results/42' and job['state'] == 'complete':
 self.reply(200, b'{"value":7}', {'Content-Type': 'application/json'})
 elif self.path == '/asset':
 if self.headers.get('If-None-Match') == '"v1"':
 self.reply(304, headers={'ETag': '"v1"'})
 else:
 self.reply(200, b'artifact', {'ETag': '"v1"'})
 else:
 self.reply(404)

 def log_message(self, *args):
 pass


server = ThreadingHTTPServer(('127.0.0.1', 0), Handler)
thread = Thread(target=server.serve_forever)
thread.start()
try:
 responses = []

 def request(method, path, headers=None):
 connection = HTTPConnection('127.0.0.1', server.server_port, timeout=5)
 try:
 connection.request(method, path, headers=headers or {})
 response = connection.getresponse()
 value = {'status': response.status, 'body': response.read().decode(),
 'location': response.getheader('Location'), 'etag': response.getheader('ETag')}
 responses.append(value)
 return value
 finally:
 connection.close()

 accepted = request('POST', '/jobs')
 assert accepted['status'] == 202 and job['state'] == 'pending'
 assert request('GET', '/results/42')['status'] == 404
 assert json.loads(request('GET', accepted['location'])['body']) == {'state': 'pending'}
 job['state'] = 'complete' # Explicit fixture transition, not a background worker.
 redirect = request('GET', '/jobs/42')
 assert redirect['status'] == 303 and redirect['location'] == '/results/42'
 assert json.loads(request('GET', redirect['location'])['body']) == {'value': 7}
 cached = request('GET', '/asset')
 validation = request('GET', '/asset', {'If-None-Match': cached['etag']})
 assert validation['status'] == 304 and validation['body'] == '' and validation['location'] is None
 assert cached['body'] == 'artifact'
 print(json.dumps({'responses': responses, 'reuse_cached_body': cached['body']}))
finally:
 server.shutdown()
 thread.join()
 server.server_close()

POST first returns 202 while the job is pending. Its result URL still returns 404, and the status resource returns 200 with a pending representation. The fixture then explicitly changes the in-memory state to complete; this is not a tested background worker. The status endpoint returns 303, and retrieving its Location returns the result value seven.

The asset’s initial GET returns artifact and ETag "v1". Sending that validator back yields 304 with no content and no Location. The caller retains the previously received bytes for reuse. This demonstrates the response contract without claiming that a browser cache was exercised.

The seven responses distinguish accepted processing, successful status retrieval, result redirection, and conditional reuse. They do not prove durable queueing or eventual completion. Review status selection together with headers, body, and state transitions: a plausible number alone cannot make an incomplete operation complete or an invalid representation usable.

Sources

RFC 9110: HTTP Semantics, precise meanings of success, redirection, and error responses, checked 2026-09-13.
MDN: HTTP response status codes, status-specific behavior and accompanying headers, checked 2026-09-13.