curl이 실패할 때 "안 된다"로 끝내지 말고, 요청이 거치는 단계(DNS → TCP 연결 → TLS → HTTP) 중 어디서 멈췄는지를 메시지로 읽어내면 원인이 좁혀집니다.
먼저 verbose로 본다
로컬 또는 서버
curl -v https://api.example.com/health
-v 출력은 단계별로 찍힙니다: 이름 해석 → Trying <IP>:443 → Connected → TLS 핸드셰이크 → 응답. 어느 줄에서 멈췄는지가 곧 원인입니다.
증상별 해석
Could not resolve host — DNS 문제. 이름이 IP로 안 풀립니다.
로컬 터미널
dig api.example.com +short # 레코드 확인
cat /etc/resolv.conf # 리졸버 설정
Connection refused — IP까지는 갔지만 그 포트에 아무도 안 듣고 있음(서비스 다운 또는 다른 포트). 방화벽이 아니라 보통 서버 측 문제.
로컬 터미널
ss -tlnp | grep :443 # 서버에서 리슨 중인지
Connection timed out — 패킷이 응답 없이 버려짐. 방화벽/보안그룹 드롭이 전형적. refused(즉시 거절)와 달리 timeout(무응답)은 중간에 막혔다는 신호.
SSL certificate problem — TCP·TLS까지 갔으나 인증서 검증 실패(만료·체인 누락·이름 불일치).
로컬 또는 서버
curl -vI https://api.example.com # 인증서·헤더 확인
openssl s_client -connect api.example.com:443 -servername api.example.com
refused vs timeout — 결정적 차이
| 증상 | 의미 | 1순위 점검 |
|---|---|---|
| Connection refused | 포트가 안 열림(즉시 거절) | 서비스 실행 여부·포트 |
| Connection timed out | 응답 없음(드롭) | 방화벽·보안그룹·네트워크 경로 |
이 둘을 구분하는 것만으로 "서버 문제"인지 "네트워크/방화벽 문제"인지가 갈립니다.
순서 요약
로컬 또는 서버
curl -v <URL> # 어느 단계에서 멈췄나
dig <host> +short # DNS
ss -tlnp | grep :<port> # 서버가 듣는지(서버에서)
openssl s_client -connect <host>:443 # TLS
DNS·포트·방화벽·TLS를 직접 끊어보고 진단하는 실습은 네트워크 트랙에서 무료로 할 수 있습니다.