Read status together with transport and application results

Thu, 03 Dec 2026 00:00:00 +0000

A caller needs more than a three-digit number to decide what happened. Did an HTTP response arrive, did its body arrive completely, and does the application result satisfy the requested operation? These are separate questions. A 200 response can carry a documented application-level failure, or its transfer can break after the headers. A connection failure before any response supplies no HTTP status at all. Preserve those distinctions in diagnostics and metrics.

Classify the evidence you received

An HTTP error response is still a response. It can contain a useful representation, authentication challenge, request identifier, or Retry-After field. Some client libraries raise exceptions for 4xx and 5xx while retaining access to those details. Catch the specific HTTP error before a broader transport exception, and read its relevant fields. Otherwise a meaningful 429 can be flattened into the same generic error as a failed connection.

A successful HTTP exchange can also be an application envelope. For example, a batch or RPC contract may return 200 while individual operations report failure in the body. Interpret the documented schema instead of assuming all such responses mean success or that every such API is necessarily violating HTTP. A monitoring check should validate the outcome it promises to monitor, including the body when that contract requires it.

When it breaks

A status recorded when headers arrive can conceal a later truncated body. Content-Length, stream termination, decompression, and parsing can all affect whether a usable representation was delivered. Report a received status and an incomplete transfer separately. Do not count a partially delivered 200 response as a successful application result simply because the status metric was incremented early.

Retry choices require more context than the first digit. 429 indicates rate limiting and may provide Retry-After. 503 can also suggest a delay. That field can use delay seconds or an HTTP date; neither form promises the server will be healthy at the requested time. Combine server guidance with a bounded policy, backoff, and the operation’s semantics instead of immediately replaying every error.

For a non-idempotent request, a lost response can leave its effect uncertain. The server might have committed before the client lost contact. Repeating without a suitable idempotency contract can duplicate work. Conversely, some 4xx conditions become recoverable after authentication, state, or rate-limit conditions change. Class-wide “always retry” and “never retry” rules erase the information needed to make that decision.

The status also does not identify which component generated it. An origin, gateway, or intermediary may send an error response. Correlate available request identifiers and logs before attributing the failure. A diagnostic value such as curl’s 000 is not a registered HTTP response status; it commonly indicates that no usable HTTP status was obtained.

Check it quickly

Save this as status-client.py and run python3 status-client.py. A temporary loopback server provides five response cases. The Python client uses the actual urllib response and exception behavior, disables proxy routing for the fixture, and performs no automatic application retry. A separately reserved, non-listening loopback port supplies a connection-refusal case without contacting an external host.

from http.client import IncompleteRead
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from threading import Thread
from urllib.error import HTTPError, URLError
from urllib.request import ProxyHandler, build_opener
import json
import socket


class Handler(BaseHTTPRequestHandler):
 def do_GET(self):
 if self.path == '/application-error':
 status, data, retry = 200, b'{"ok":false,"error":"demo"}', None
 elif self.path == '/busy':
 status, data, retry = 503, b'{"error":"unavailable"}', '3'
 elif self.path == '/limit':
 status, data, retry = 429, b'{"error":"limited"}', '2'
 else:
 status, data, retry = 404, b'{"error":"missing"}', None
 if self.path == '/truncated':
 self.send_response(200)
 self.send_header('Content-Length', '100')
 self.end_headers()
 self.wfile.write(b'partial')
 return
 self.send_response(status)
 self.send_header('Content-Type', 'application/json')
 self.send_header('Content-Length', str(len(data)))
 if retry:
 self.send_header('Retry-After', retry)
 self.end_headers()
 self.wfile.write(data)

 def log_message(self, *args):
 pass


opener = build_opener(ProxyHandler({}))


def inspect(url):
 try:
 try:
 response = opener.open(url, timeout=3)
 except HTTPError as error:
 response = error
 with response:
 result = {'http_status': response.code, 'retry_after': response.headers.get('Retry-After')}
 try:
 body = response.read()
 except IncompleteRead:
 return {**result, 'complete_body': False}
 return {**result, 'complete_body': True, 'payload': json.loads(body)}
 except URLError:
 return {'http_status': None, 'transport_failure': True}


server = ThreadingHTTPServer(('127.0.0.1', 0), Handler)
thread = Thread(target=server.serve_forever)
thread.start()
try:
 origin = f'http://127.0.0.1:{server.server_port}'
 results = {path: inspect(origin + path) for path in
 ('/application-error', '/busy', '/limit', '/missing', '/truncated')}
 with socket.socket() as reserved:
 reserved.bind(('127.0.0.1', 0)) # Bound without listen: no HTTP server on this port.
 results['connection-refused'] = inspect(f'http://127.0.0.1:{reserved.getsockname()[1]}/')
 assert results['/application-error']['http_status'] == 200
 assert results['/application-error']['payload']['ok'] is False
 assert results['/busy']['http_status'] == 503 and results['/busy']['retry_after'] == '3'
 assert results['/limit']['http_status'] == 429 and results['/limit']['retry_after'] == '2'
 assert results['/missing']['http_status'] == 404
 assert results['/truncated'] == {'http_status': 200, 'retry_after': None, 'complete_body': False}
 assert results['connection-refused'] == {'http_status': None, 'transport_failure': True}
 print(json.dumps(results))
finally:
 server.shutdown()
 thread.join()
 server.server_close()

The application envelope has HTTP 200 and ok: false. The busy and limited endpoints yield 503 and 429, retaining Retry-After values three and two. The missing endpoint remains an HTTP 404 response rather than becoming a transport error. All four bodies are complete and parseable in this fixture.

The truncated endpoint advertises one hundred bytes but sends only partial. Headers provide status 200, then reading the body raises IncompleteRead and the result records incomplete content. The connection-refusal case has no HTTP status. The final assertions require all six classifications to remain distinct.

These results test classification, not server recovery or the safety of replaying a write. Keep the received status, transfer completion, and application outcome available to the component that decides the next action. That lets an operator distinguish refusal, incomplete delivery, and a fully delivered negative answer without guessing from one flattened success flag.

Sources

RFC 9110: HTTP Semantics, status interpretation, retries, and Retry-After, checked 2026-09-13.
RFC 6585: additional HTTP status codes, the meaning of 429 Too Many Requests, checked 2026-09-13.
Python 3.14: urllib.request, HTTP response objects and error handling, checked 2026-09-13.

Status · XB Field Notes

Read status together with transport and application results

Classify the evidence you received

When it breaks

Check it quickly

Sources