curl 에러를 숫자 하나로 넘기지 않기: --fail-with-body와 -w를 같이 쓰는 습관

2026년 4월 6일 | 개발 깨알 팁

---

나는 API를 확인할 때 curl을 자주 쓰는데, 예전에는 실패 응답을 너무 자주 놓쳤다. 500이든 401이든 일단 종료 코드만 보고 넘어가고, 막상 왜 실패했는지는 다시 로그를 열거나 서버 쪽 콘솔을 뒤져야 했다. 특히 배치 작업이나 CI처럼 출력이 길게 쌓이는 환경에서는 이 한 번의 왕복이 생각보다 크다.

그 뒤로는 실패를 감추지 말고, 응답 본문과 요약 지표를 한 번에 같이 남기자는 쪽으로 습관이 바뀌었다. 내가 가장 자주 쓰는 조합은 --fail-with-body와 -w다. 하나는 HTTP 실패를 정상 응답처럼 삼키지 않게 막아 주고, 다른 하나는 상태 코드와 총 소요 시간을 마지막 줄에 붙여 준다.

실패를 바로 읽히게 만드는 기본 조합

curl --silent --show-error \
  --fail-with-body \
  -w '\n[http_code=%{http_code} total=%{time_total}s]\n' \
  'https://api.example.com/v1/jobs/123'

이렇게 해 두면 성공일 때는 본문 뒤에 요약 줄이 붙고, 실패일 때도 서버가 내려준 에러 JSON을 그대로 볼 수 있다. 예를 들어 {"error":"token expired"} 같은 메시지가 남으면, 단순히 401이 났다는 사실보다 훨씬 빨리 원인을 좁힐 수 있다. 반대로 --fail만 쓰면 본문이 사라져서 숫자만 보고 다시 재현해야 하는 경우가 많다.

내가 같이 보는 값은 두 개면 충분했다

• http_code: 인증 실패인지, 서버 오류인지, 리다이렉트 문제인지 바로 구분된다.
• time_total: 같은 500이어도 즉시 실패인지, 한참 기다리다 죽는지 감이 잡힌다.

여기에 값을 너무 많이 붙이면 오히려 로그가 다시 흐려진다. 나는 보통 상태 코드 하나, 총 시간 하나만 먼저 남긴다. 이 두 줄만 있어도 네트워크 문제인지, 권한 문제인지, 서버 처리 지연인지 1차 분류가 꽤 빨라진다.

짧은 팁이지만 차이가 나는 지점

이 습관이 특히 유용한 순간은 자동화 스크립트가 조용히 실패할 때다. 표면상으로는 그냥 "요청 실패" 한 줄만 남는데, 실제로는 본문 안에 재시도 가능 여부나 제한 사유가 적혀 있는 경우가 많다. 그 정보를 처음부터 같이 남겨 두면, 같은 실패를 다시 호출해서 재현하는 비용이 줄어든다.

요약하면 나는 이제 curl 실패를 종료 코드만으로 읽지 않는다. 실패 본문을 버리지 않고, 마지막에 상태 코드와 시간을 붙여 놓는다. 작은 습관인데도 API 디버깅 속도가 꽤 달라진다. 특히 여러 서비스가 이어진 호출 체인에서는 이 한 줄이 다음 판단을 훨씬 덜 막막하게 만들어 준다.