Around Go: command line · 3 MIN READ

HTTP debugging: curl, status codes and time budgets

Probe a local API and separate DNS, connection, HTTP and application failures.

An API can fail before any handler runs, or return an HTTP error over a perfectly healthy connection. curl helps identify that boundary. These examples target your own local Go service at 127.0.0.1:8080 with a /healthz endpoint; adjust the paths to your application.

Inspect headers and keep a timeout

-i includes response headers, --connect-timeout bounds connection establishment, and --max-time bounds the total operation. --fail-with-body makes HTTP 4xx/5xx nonzero while retaining the response body, unlike an ordinary successful curl transport.

bash

curl -i --connect-timeout 2 --max-time 5 \
  --fail-with-body http://127.0.0.1:8080/healthz

Read the code

Expect a successful health response from your server. Connection refused means no reachable listener at that address, not an HTTP 500. A timeout has a different cause again; retain the specific diagnostic instead of reducing all failures to unavailable.

Send JSON without hiding the request contract

--data-binary sends the provided bytes. The content type declares JSON, but the server still has to validate fields. This request is an example for a local /notes route accepting a text field; it is not an endpoint supplied by every Go service.

bash

curl -i --max-time 5 --fail-with-body \
  -H "Content-Type: application/json" \
  --data-binary '{"text":"inspect this request"}' \
  http://127.0.0.1:8080/notes

Read the code

The single quotes keep Bash from interpreting the JSON double quotes. Data selects POST by default. Do not add a production authorization token to a shared example, shell history or a screenshot.

Measure and reason about the failed layer

--write-out prints transport timing after the request; -o /dev/null discards the body in this diagnostic. An HTTP status of 000 is not a server status: no HTTP response was received. Inspect hostname resolution separately when using a domain.

bash

curl -sS -o /dev/null --max-time 5 \
  -w 'status=%{http_code} connect=%{time_connect}s total=%{time_total}s\n' \
  http://127.0.0.1:8080/healthz

Read the code

This timing command does not use --fail-with-body, so an HTTP 500 can still have curl status zero. Check both the printed HTTP status and the process outcome. Avoid -k as a default fix for TLS errors; correct the hostname and trust configuration.

TAKE THIS WITH YOU

Check transport errors, HTTP status and response body separately. Bound diagnostic requests and preserve the failed layer before deciding whether the problem is routing, TLS, a handler or a downstream dependency.

Check your understanding

What does curl --fail-with-body add for HTTP 4xx or 5xx?

Go to the source

Progress stays in this browser. No account needed.