curl API 에러에서 본문 버리지 않기: --fail-with-body와 -w 같이 보기

2026년 4월 14일 | 개발 깨알 상식_Tips

---

curl로 401, 404, 500을 확인할 때 제일 허무한 순간은 종료 코드만 남고 서버가 내려준 실패 본문이 사라질 때다. API는 실패 이유를 JSON으로 꽤 친절하게 돌려주는 경우가 많은데, 막상 스크립트 쪽에서는 숫자 하나만 남고 왜 틀렸는지 다시 재현해야 하는 장면이 자주 나온다. 나는 이럴 때 실패 판정과 본문 보존을 따로 본다.

기본 조합은 단순하다. --fail-with-body로 HTTP 4xx/5xx를 실패로 올리되 본문은 남기고, -sS로 progress meter는 끄되 에러 메시지는 살리고, 마지막에 -w로 상태 코드와 시간을 짧게 붙인다. 핵심은 출력 줄을 많이 늘리는 게 아니라, 실패 이유를 다시 찾으러 가지 않게 만드는 것이다.

Figure 1. -f는 실패를 빨리 올려주지만 본문을 버리고, --fail-with-body는 같은 실패 판정을 유지한 채 서버 설명까지 같이 남긴다.

1. -f보다 --fail-with-body가 먼저인 이유

curl 매뉴얼 설명이 꽤 명확하다. --fail-with-body는 응답 코드가 400 이상일 때 에러 22를 반환하지만, 동시에 서버가 내려준 본문은 출력하고 저장한다. 반대로 -f는 같은 상황에서 빠르게 실패시키는 대신 본문을 남기지 않는다. 인증 만료, rate limit, validation error처럼 실패 이유가 응답 본문 안에 적혀 있는 API에서는 이 차이가 생각보다 크게 난다.

• -f: 실패는 빨리 잡히지만, 왜 실패했는지는 다시 봐야 한다.
• --fail-with-body: 실패 판정은 유지하면서 에러 JSON도 같이 남긴다.
• -sS: 진행 바는 숨기되, 실제 실패 메시지는 지우지 않는다.

나는 API 디버깅에서는 보통 두 번째가 먼저라고 본다. 특히 배치 로그나 CI에서는 "401"보다 {"error":"token expired"}가 훨씬 빨리 다음 행동을 결정해 준다. 숫자만 남으면 다시 호출해 보고, 헤더를 다시 보고, 토큰 만료인지 권한 부족인지 한 번 더 거슬러 올라가야 한다.

2. -w는 본문과 섞지 말고 요약 줄로만 두기

여기서 내가 같이 두는 옵션이 -w, 즉 --write-out이다. 매뉴얼 기준으로 이 옵션은 전송이 끝난 뒤 변수 치환 형식으로 요약 정보를 붙인다. 요즘은 %{response_code}를 쓰는 편이 더 낫다. 문서에도 나오듯 이 값은 예전 http_code의 새 이름이다. 나는 여기에 %{time_total}만 같이 남긴다.

curl -sS   --fail-with-body   -w '
%{stderr}[code=%{response_code} total=%{time_total}s]
'   'https://api.example.com/v1/jobs/123'

여기서 작은 포인트가 하나 더 있다. %{stderr}를 앞에 넣어두면 -w 출력이 표준 에러로 빠진다. 이러면 응답 본문은 표준 출력에 그대로 남고, 상태 코드·시간 요약만 따로 떨어진다. 본문을 jq로 넘기거나 파일로 저장할 때 이 구분이 꽤 편하다. 본문은 본문대로 기계가 읽고, 요약은 사람이 로그에서 바로 본다는 분리가 생긴다.

3. 내가 먼저 남겨두는 값은 두 개면 충분했다

요약 줄에 값을 너무 많이 붙이면 다시 잡음이 된다. 나는 보통 아래 둘만 먼저 본다.

• response_code: 인증 실패인지, 요청 형식 오류인지, 서버 오류인지 1차 분류가 빨라진다.
• time_total: 즉시 거절인지, 오래 기다리다 실패했는지 감이 잡힌다.

이 두 값만 있어도 재시도 전략이 꽤 빨리 정해진다. 401이면 자격증명부터 보고, 429면 제한 정책을 보고, 500인데 시간이 길면 서버 처리 구간이나 upstream 호출을 의심하게 된다. 짧은 팁이지만 실패를 숫자 하나로만 읽지 않기 시작점으로는 이 조합이 가장 덜 번거로웠다.

정리하면 나는 이제 curl 실패를 exit code만으로 끝내지 않는다. --fail-with-body로 본문을 남기고, -sS로 조용한 실패를 막고, -w로 마지막 줄에 상태 코드와 시간을 붙인다. 자동화 스크립트에서 API를 자주 두드린다면, 이 한 줄만으로도 "왜 실패했는지 다시 찾으러 가는 왕복"이 꽤 줄어든다.