The error paths

A service is judged by what it does when something is wrong. The service of the previous page has four failures, and each one was triggered here with a real request against a real server. The server file is on that page; this one runs it.

A body of the wrong length

The fixed endpoint takes thirty bytes. A client that sends twenty-nine has already broken the contract, and the answer is a 400 with the count, before the core is started:

printf 'C00001WIDGET0100002000123456N' | curl -s -w '\n%{http_code}\n' \
    -X POST --data-binary @- http://127.0.0.1:8765/price

{"error": "request must be 30 bytes", "got": 29}

400

The JSON endpoint refuses values the fixed record cannot hold, and it refuses them the same way:

curl -s -w '\n%{http_code}\n' -X POST -d '{"order_id":"C00009","sku":"WIDGET09","qty":1,"price_cents":100,"region":"Q7"}' \
    http://127.0.0.1:8765/price/json

{"error": "unknown region Q7"}

400

A rejected order

A well-formed request that the business rules refuse is not a client error of the same kind: the core priced it, looked at it, and said why. The status is 422 and the body is the fifty-byte answer with the reason in the message:

printf 'C00003WIDGET0300001000100000X9' | curl -s -w '\n%{http_code}\n' \
    -X POST --data-binary @- http://127.0.0.1:8765/price

C00003080000000000000000000000UNKNOWN REGION

422

The distinction between 400 and 422 is worth keeping: the first says the caller cannot speak the protocol, the second says the caller spoke it and the answer is no. A client library can retry one and must not retry the other.

A core that is missing

The core is a file in the service directory, and a deployment that forgets it starts a service that serves nothing. The second server was started with PRICE_CORE=/nonexistent/price:

PRICE_CORE=/nonexistent/price python3 -I server.py 8766 &
printf 'C00001WIDGET0100002000123456N1' | curl -s -w '\n%{http_code}\n' \
    -X POST --data-binary @- http://127.0.0.1:8766/price

{"error": "core could not start", "detail": "[Errno 2] No such file or directory: '/nonexistent/price'"}

500

The /health endpoint of the same server reports the problem before a request does:

{"status": "ok", "core": "/nonexistent/price", "core_exists": false}

That body is the one a deployment check should read. The word ok is the service being able to answer, and core_exists is the core being there; a check that only looks at the HTTP status of /health would pass on a container with no COBOL at all.

A core that is too slow

The timeout is the failure a client cannot cause and cannot see: the core starts, reads its request, and does not finish. To produce one, a fake core that sleeps for five seconds, with the timeout set to one:

#!/bin/sh sleep 5

PRICE_CORE=./slowcore.sh PRICE_TIMEOUT=1 python3 -I server.py 8767 &
time (printf 'C00001WIDGET0100002000123456N1' | curl -s -w '\n%{http_code}\n' \
    -X POST --data-binary @- http://127.0.0.1:8767/price)

{"error": "core timed out", "timeout": 1.0}

504

real    0m1.017s
user    0m0.003s
sys     0m0.009s

The 504 arrives one second after the request, which is the timeout and not the five seconds of the fake core: the subprocess was killed by subprocess.run and the service answered while the child was gone. Without that timeout the server would hold the connection for as long as the core felt like running, and a stuck core would take the whole service down one worker at a time.

What each failure is

FailureStatusBodyWhere it is decided
body is not 30 bytes400JSON with the lengthPython, before the core
JSON value out of range400JSON with the reasonPython, before the core
order rejected by the rules422the 50-byte answerthe core\'s status field
core file missing500JSON with errno textPython, on OSError
core slower than the timeout504JSON with the timeoutPython, on TimeoutExpired
wrong path404JSON with the pathPython, routing

The next page tests these paths from Python, with the real server and the real core, on a port nobody else is using.

The COBOL was built with cobc (GnuCOBOL) 3.2.0 with -O2, the service runs on Python 3.14.10 with the standard library only, and both ran on Alpine Linux 3.24.3 (x86_64) in a Docker container with nproc 4.

Article author: Arthur Isaev

Banner image