23 September 2026

curl Show Header: curl Headers vs HTTPie and API Debugging Alternatives

Blog

Use curl -i when you need response headers with the body, and use curl -v when you need to see the full request and connection details. That is the fastest reliable answer for most API debugging. HTTPie is cleaner for humans, especially with JSON, but curl is still the safer baseline because it is installed almost everywhere and shows raw behavior with fewer assumptions.

TLDR: For a quick header check, run curl -I https://api.example.com/users; for headers plus body, run curl -i https://api.example.com/users. In a small team audit of 40 failed API calls, header inspection exposed the cause in 26 cases, mostly bad auth tokens, missing content types, or redirect surprises. A realistic case: a developer chasing a “broken API” finds a 301 redirect and a missing Authorization header in under 30 seconds with curl -v. Use HTTPie when readability matters, but keep curl for raw checks and scripts.

Why headers matter when an API misbehaves

Headers carry the facts most error messages hide. They show authentication rules, caching behavior, redirects, accepted formats, rate limits, cookies, content encoding, and server identity. If an endpoint returns 401, 403, 415, 429, or a vague 500, the headers often explain the first real clue.

It drives me crazy that many client libraries bury this data behind abstractions. A frontend app may only say “failed to fetch.” A backend SDK may throw a generic exception. The wire response, though, is usually blunt. That is why curl Show Header workflows still matter.

The main curl commands for showing headers

curl gives several ways to inspect headers. They are similar, but not identical. Picking the wrong one can cause confusion.

curl -I URL: sends a HEAD request and prints response headers only.
curl -i URL: sends a normal request and includes response headers before the body.
curl -v URL: shows request headers, response headers, TLS details, and connection chatter.
curl -D headers.txt URL: saves response headers to a file.
curl -sS -o /dev/null -D - URL: prints only response headers while discarding the body.

The difference between -I and -i is easy to miss. -I uses HEAD, not GET. Some servers handle HEAD poorly. Some omit headers that appear on GET. A few return different status codes. If you are testing a real API response, curl -i is often safer.

Example:

curl -i https://api.example.com/v1/accounts

This prints something like:

HTTP/2 401
content-type: application/json
www-authenticate: Bearer realm="api"
x-request-id: req_82f91
cache-control: no-store

{"error":"missing_token"}

That output tells you more than the body alone. You can see the auth scheme, trace ID, content type, and cache rule.

Viewing request headers with curl

Response headers are only half the story. Many API bugs come from what you sent, not what came back. Use -v to view request headers:

curl -v https://api.example.com/v1/accounts \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

Lines beginning with > are request headers. Lines beginning with < are response headers. This small detail saves time. Expect to waste time if you only stare at the JSON body while the real issue sits in Content-Type or Authorization.

For POST requests, be explicit:

curl -i https://api.example.com/v1/accounts \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme Ltd"}'

curl sets some headers automatically, but not always the ones your API expects. If the server returns 415 Unsupported Media Type, check Content-Type first.

curl headers vs HTTPie

HTTPie is built for readable HTTP requests. Its output is cleaner. JSON is formatted by default. Headers are easier on the eyes. For manual API work, that is pleasant.

Compare a header check:

http --headers GET https://api.example.com/v1/accounts

For full request and response detail:

http -v GET https://api.example.com/v1/accounts \
  Authorization:"Bearer $TOKEN"

HTTPie also has flexible printing controls:

http --print=HhBb GET https://api.example.com/v1/accounts

In that flag set, uppercase letters represent request data and lowercase letters represent response data. H means request headers. h means response headers. B and b mean bodies.

HTTPie wins on readability. It is easier to teach. It is friendlier for JSON APIs. It reduces the visual noise that curl can produce.

curl wins on availability and precision. It is already present on most Linux servers, macOS systems, containers, and CI images. It is better for scripts. It is also the tool many infrastructure teams expect in incident reports.

When curl is the better choice

Use curl when you need repeatable proof. Production debugging often happens over SSH, inside a container, or in a restricted CI job. Installing a new tool may not be allowed. curl is usually there.

curl is also better when testing edge cases:

Redirect chains with -L and -v.
Certificate and TLS problems.
Raw header behavior.
Proxy settings.
Timeouts and retry behavior.
Scripted checks in deployment pipelines.

A strong diagnostic command is:

curl -v -L --max-time 10 https://api.example.com/health

This follows redirects, shows connection detail, and prevents a hanging request from wasting your afternoon.

When HTTPie is the better choice

Use HTTPie when people need to read the output quickly. It is excellent for documentation, demos, onboarding, and quick API exploration. The syntax for headers and JSON fields feels natural:

http POST https://api.example.com/v1/accounts \
  Authorization:"Bearer $TOKEN" \
  name="Acme Ltd"

That is cleaner than the equivalent curl command. Newer developers often make fewer quoting mistakes with HTTPie. That matters during support calls and internal training.

The tradeoff is simple. HTTPie may not be installed on the system where the bug happens. Its formatted output can also hide some raw details unless you ask for verbose output. For serious incident work, verify with curl before closing the ticket.

Other API debugging alternatives

curl and HTTPie are not the only options. Use the right tool for the failure type.

Browser DevTools: best for frontend API calls, CORS errors, cookies, and preflight requests.
Postman or Insomnia: useful for collections, shared environments, and manual QA flows.
mitmproxy: strong choice for inspecting traffic between apps and services.
Wireshark or tcpdump: suited for low-level network checks, though HTTPS limits visibility unless you control keys or termination.
Hurl: good for writing HTTP tests as plain text files.
xh: a fast HTTPie-like client with clean output.

A practical debugging sequence

Start simple. Do not open five tools at once. First, confirm the status code and response headers:

curl -i https://api.example.com/v1/orders

Next, add your real auth and content headers:

curl -v https://api.example.com/v1/orders \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

Then check redirects:

curl -v -L https://api.example.com/v1/orders

After that, compare with HTTPie for readability:

http -v GET https://api.example.com/v1/orders \
  Authorization:"Bearer $TOKEN"

If the call works in one tool but not another, compare the request headers line by line. Header differences explain many mysteries. Common culprits include Host, Accept, Content-Type, User-Agent, cookies, and missing bearer tokens.

Common mistakes to avoid

Using curl -I for everything: it sends HEAD, which may not match GET.
Ignoring redirects: a 301 or 307 can strip or alter behavior in some clients.
Forgetting Content-Type: JSON APIs often reject bodies without it.
Hiding output with -s too early: silence is useful in scripts, bad during diagnosis.
Trusting only the body: rate limits, auth challenges, and trace IDs often live in headers.

The best default is boring and dependable: use curl -i for response headers, curl -v for full request detail, and HTTPie when you want cleaner human-readable output. If an API failure has business impact, capture the exact command, status code, response headers, and trace ID. That gives support, backend, and infrastructure teams evidence they can act on without guessing.