← All cheatsheets

Network

HTTP & curl — make, read, and debug requests

Build any HTTP request from the terminal, read what came back, and trace a failing call from status line to TLS to timing.

Docs-checkedhttpcurltlsheadersdebugging

Quick reference — reach for these first

GETcurl shipreadymetrics.comBasic request. curl adds https:// if you omit the scheme on a bare host.
inspectcurl -sSI scm.ccHeaders only (-I), silent but keep errors (-sS). Read the status line first.
timingcurl -sS -o /dev/null -w '%{http_code} %{time_total}s' scm.ccStatus + total time, no body. Which phase is slow comes next.
POST jsoncurl -X POST -H "Content-Type: application/json" -d '{"k":"v"}' scm.ccSet the type AND send the body. A 415 means the header is missing.
authcurl -H "Authorization: Bearer TOKEN" scm.ccBearer token. 401 = bad/missing token; 403 = valid token, no access.

What the status code tells you

curl request and the meaning of each status class A request goes from client to server; the response falls into 2xx success, 3xx redirect, 4xx your request, or 5xx the server. curl server client request response server 2xx · it worked 3xx · go elsewhere 4xx · your request 5xx · the server 401/403 → auth 404 → wrong path 502/504 → upstream

Text equivalent: A curl request goes from client to server and a response comes back. The status code's first digit tells you who owns the problem: 2xx succeeded, 3xx redirects elsewhere, 4xx is your request (401/403 auth, 404 wrong path), 5xx is the server (502/504 a bad or slow upstream).

Common tasks

Task · Command · What to check

TaskCommandWhat to check
Follow redirectscurl -L scm.ccFinal URL and status; -I -L shows each hop.
See the full exchangecurl -v scm.cc> request lines, < response lines, * TLS/connection notes.
Headers onlycurl -sSI scm.ccStatus line, Content-Type, Set-Cookie, cache headers.
Send a form bodycurl -d "email=a@b.co&plan=pro" scm.ccImplies application/x-www-form-urlencoded.
Send JSON from a filecurl -H 'Content-Type: application/json' --data-binary @body.json scm.cc--data-binary keeps newlines; -d strips them.
Basic authcurl -u USER:PASS scm.cc401 cleared? Prefer -u over putting creds in the URL.
Custom methodcurl -X DELETE -H 'Authorization: Bearer TOKEN' scm.cc/items/42Response status; 405 means the method isn't allowed.
Time each phasecurl -w '@curl-format.txt' -o /dev/null -sS scm.ccDNS vs connect vs appconnect(TLS) vs starttransfer(TTFB).
Force HTTP/1.1 or /2curl --http1.1 scm.ccRule out an HTTP/2 negotiation issue.
Inspect the TLS certcurl -vI https://app.shipreadymetrics.com 2>&1 | grep -iE 'subject|expire|issuer'SNI matches, not expired, chain complete.
Save the responsecurl -O https://app.shipreadymetrics.com/report.csv-O keeps the remote name; -o NAME renames.
Resume a downloadcurl -C - -O https://app.shipreadymetrics.com/big.tarPicks up where an interrupted transfer stopped.

Worked example — a POST returns 401

TRACE IT

1
Reproduce and read the status line only.
curl -sS -o /dev/null -w '%{http_code}\n' \
  -X POST -H "Authorization: Bearer $TOKEN" scm.cc/api/jobs
# 401
2
Is the header actually being sent? Watch the request.
curl -v -X POST -H "Authorization: Bearer $TOKEN" scm.cc/api/jobs 2>&1 | grep -i '^> auth'
# (empty) → $TOKEN was unset, so no header went out
3
Confirm the token is actually set.
echo "${#TOKEN} chars"   # 0 means the var is empty
# 0 chars
✓
Export a real token, retry, and verify a 2xx. 401 → 201 confirms it was a missing header, not a bad credential.

Troubleshooting — symptom → first check → next check

SymptomFirst checkEstablishesNext check
401 Unauthorizedcurl -v … | grep '^> auth'Header sent vs token rejectedCheck token value / scope
403 ForbiddenRe-read the response bodyAuthenticated but not allowedCheck role / resource ownership
404 Not Foundcurl -IL scm.cc/pathWrong path vs missing redirectConfirm base URL + trailing slash
415 Unsupported MediaEcho your -H flagsContent-Type missing/wrongAdd -H 'Content-Type: application/json'
SSL certificate problemcurl -vI https://HOSTExpiry / chain / SNITest with --resolve or -servername
502 / 504curl -w '%{time_total}'Upstream down vs slowCheck backend health + timeouts

References

Assumes curl ≥ 7.75 on Linux/macOS. app.shipreadymetrics.com and scm.cc are used as example hosts; replace with your own. Placeholders in CAPS.