네트워크
curl 종료 코드(exit code) 목록
curl 명령어가 반환하는 exit code(종료 코드)의 의미・흔한 원인・해결 방법을 정리했습니다. CI/CD 파이프라인과 셸 스크립트를 디버깅할 때 유용한 개발자용 레퍼런스이며, 코드 번호를 입력하는 상세 검색 기능도 제공합니다.
curl exit code 목록
| 코드 | 상수명 | 의미 | 흔한 원인 |
|---|---|---|---|
| 연결・초기화 오류 | |||
| 1 | CURLE_UNSUPPORTED_PROTOCOL | URL에 지정된 프로토콜을 curl이 지원하지 않음을 나타냅니다. | 빌드 시 해당 프로토콜（예: gopher, ldap）이 비활성화된 curl 바이너리를 사용하고 있거나, URL 스킴 부분의 오타가 원인입니다. |
| 2 | CURLE_FAILED_INIT | curl의 내부 초기화에 실패했음을 나타냅니다. | 메모리 부족이나 환경 이상 등 드물게 발생하는 저수준 초기화 실패입니다. |
| 3 | CURLE_URL_MALFORMAT | 지정된 URL의 형식이 잘못되어 curl이 해석할 수 없음을 나타냅니다. | URL에 스킴이 누락되었거나（http:// 누락）, 잘못된 문자가 포함되어 있을 때 발생합니다. |
| 5 | CURLE_COULDNT_RESOLVE_PROXY | 지정한 프록시 서버의 호스트명 확인（resolve）에 실패했음을 나타냅니다. | --proxy에 지정한 호스트명 오류, 또는 프록시용 DNS가 이름을 확인하지 못하는 상태입니다. |
| 6 | CURLE_COULDNT_RESOLVE_HOST | 접속 대상 호스트의 이름 확인（DNS）에 실패했음을 나타냅니다. | 도메인명 오타, DNS 서버 장애, 오프라인 환경에서의 실행이 대표적인 원인입니다. |
| 7 | CURLE_COULDNT_CONNECT | 이름 확인은 성공했지만 서버와의 TCP 연결 수립에 실패했음을 나타냅니다. | 포트 번호 오류, 방화벽에 의한 차단, 서버 다운 상태일 때 발생합니다. |
| 8 | CURLE_WEIRD_SERVER_REPLY | 서버로부터 curl이 해석할 수 없는 예기치 않은 형식의 응답을 받았음을 나타냅니다. | FTP 서버가 비표준 응답을 반환하거나, 다른 프로토콜을 사용하는 서버에 실수로 접속했을 때 발생하기 쉽습니다. |
| 9 | CURLE_REMOTE_ACCESS_DENIED | 서버에 연결은 되었지만 접근이 거부되었음을 나타냅니다. | FTP 디렉터리에 대한 접근 권한 부족, 또는 서버 측 IP 제한에 해당할 때 발생합니다. |
| 데이터 전송 오류 | |||
| 18 | CURLE_PARTIAL_FILE | 전송이 완료되기 전에 중단되어 파일 일부만 수신되었음을 나타냅니다. | 네트워크의 순간적인 단절, 또는 서버 측이 예고한 Content-Length에 도달하기 전에 연결을 끊었을 때 발생합니다. |
| 23 | CURLE_WRITE_ERROR | 로컬 디스크나 콜백 대상에 데이터를 쓰는 데 실패했음을 나타냅니다. | 디스크 용량 부족, 또는 출력 파일에 쓰기 권한이 없을 때 발생합니다. |
| 26 | CURLE_READ_ERROR | 업로드할 로컬 파일 읽기에 실패했음을 나타냅니다. | -T/--upload-file로 지정한 파일이 존재하지 않거나, 읽기 권한이 없을 때 발생합니다. |
| 52 | CURLE_GOT_NOTHING | 서버에 연결은 되었지만 응답을 전혀 받지 못했음을 나타냅니다. | 서버 프로세스가 요청 도중 크래시하거나, 빈 응답을 반환하는 설정 오류가 대표적인 원인입니다. |
| 55 | CURLE_SEND_ERROR | 네트워크로 데이터를 전송하는 데 실패했음을 나타냅니다. | 연결이 수립된 직후 상대측이 연결을 끊거나, 로컬 네트워크 인터페이스 이상으로 발생합니다. |
| 56 | CURLE_RECV_ERROR | 네트워크로부터 데이터를 수신하는 데 실패했음을 나타냅니다. | 통신 도중 상대측이 예기치 않게 연결을 재설정했을 때（Connection reset by peer） 많이 발생합니다. |
| 63 | CURLE_FILESIZE_EXCEEDED | --max-filesize로 지정한 상한을 파일 크기가 초과했음을 나타냅니다. | 예상보다 큰 응답을 받으려다 안전을 위해 설정한 상한에 걸렸을 때 발생합니다. |
| 78 | CURLE_REMOTE_FILE_NOT_FOUND | 원격 서버에 지정한 파일이 존재하지 않음을 나타냅니다（FTP 등）. | FTP 경로의 오타, 또는 대상 파일이 이미 삭제・이동되었을 때 발생합니다. |
| SSL/TLS 인증서 오류 | |||
| 35 | CURLE_SSL_CONNECT_ERROR | SSL/TLS 핸드셰이크 과정에서 문제가 발생하여 연결을 수립하지 못했음을 나타냅니다. | 서버와 클라이언트가 지원하는 TLS 버전・암호 스위트가 일치하지 않을 때 발생하기 쉽습니다. |
| 51 | CURLE_PEER_FAILED_VERIFICATION | 서버 인증서 검증에 실패했음을 나타냅니다（인증서 내용이 호스트명과 일치하지 않는 경우 등）. | 자체 서명 인증서에 접근하거나, 인증서의 Common Name / SAN이 접속 대상 호스트명과 다를 때 발생합니다. |
| 58 | CURLE_SSL_CERTPROBLEM | 로컬에서 지정한 클라이언트 인증서에 문제가 있음을 나타냅니다. | --cert로 지정한 인증서 파일의 형식 오류, 또는 암호 문구 입력 실수가 대표적인 원인입니다. |
| 60 | CURLE_SSL_CACERT | 서버 인증서를 검증하기 위한 CA 인증서 체인을 확인할 수 없었음을 나타냅니다. | CA 인증서 번들이 오래되었거나, 사내 프록시 등의 자체 서명 CA가 신뢰 저장소에 등록되어 있지 않을 때 발생합니다. 회피책으로 -k/--insecure가 있지만 운영 환경에서의 사용은 권장하지 않습니다. |
| HTTP・인증 오류 | |||
| 22 | CURLE_HTTP_RETURNED_ERROR | -f/--fail 옵션을 지정했을 때, HTTP 응답이 400번대 이상의 오류 상태였음을 나타냅니다. | CI/CD 스크립트에서 curl -f를 사용해 API가 오류 상태를 반환했을 때 이를 실패로 감지할 목적으로 발생시킵니다. |
| 67 | CURLE_LOGIN_DENIED | 서버 로그인（인증）이 거부되었음을 나타냅니다. | 사용자명・비밀번호 오류, 또는 FTP/SMTP 등의 계정 잠금이 대표적인 원인입니다. |
| 기타 | |||
| 27 | CURLE_OUT_OF_MEMORY | curl 실행 중 메모리 확보에 실패했음을 나타냅니다. | 메모리가 부족한 환경에서 대용량 파일을 처리하려는 경우 등 드문 상황에서 발생합니다. |
| 28 | CURLE_OPERATION_TIMEDOUT | --connect-timeout/--max-time 등으로 지정한 제한 시간 내에 작업이 완료되지 않았음을 나타냅니다. | 서버 응답 지연, 네트워크 지연, 또는 타임아웃 값을 너무 짧게 설정했을 때 발생하는, CI에서 가장 흔한 오류 중 하나입니다. |
| 47 | CURLE_TOO_MANY_REDIRECTS | --max-redirs로 지정한 리다이렉트 횟수 상한을 초과했음을 나타냅니다. | 리다이렉트 루프（301/302가 순환）, 또는 기본 상한（50회）을 넘는 정상적인 리다이렉트 체인에서 발생합니다. |
팁
- exit code는 직후에
$?（Bash）나%errorlevel%（Windows）로 확인할 수 있습니다. 셸 스크립트에서는curl ... || echo "failed with $?"처럼 분기 처리에 활용하면 편리합니다. - 28（타임아웃）과 7（연결 실패）은 혼동하기 쉽지만, 28은 연결 후 응답이 느릴 때, 7은 애초에 TCP 연결 자체가 수립되지 않을 때 반환된다는 차이가 있습니다.
- 60（CA 인증서 오류）이 발생했다고 해서 섣불리
-k/--insecure로 회피하지 말고, 먼저 CA 인증서 번들（ca-certificates）이 최신 상태인지 확인하세요. 운영 환경에서 -k를 상시 사용하면 중간자 공격의 위험이 커집니다. - 22（HTTP 오류）는
-f/--fail옵션을 지정했을 때만 발생합니다. 지정하지 않으면 curl은 404나 500을 받아도 exit code 0（성공）을 반환하므로, CI에서 실패를 감지하고 싶다면 반드시 -f를 붙이세요.
자주 묻는 질문
curl 명령어 실행 직후, Bash/Zsh에서는
echo $?, Windows 명령 프롬프트에서는 echo %errorlevel%, PowerShell에서는 $LASTEXITCODE로 확인할 수 있습니다.먼저
--connect-timeout과 --max-time 설정값을 점검하고 필요하면 늘려보세요. 서버 응답이 지속적으로 느리다면 서버 부하 상황과 네트워크 경로（프록시・VPN 등）도 함께 확인해야 합니다.서로 다른 것입니다. HTTP 상태 코드（404나 500 등）는 서버가 반환하는 프로토콜 수준의 응답이고, curl exit code는 curl 명령어 자체의 실행 결과（연결 실패・타임아웃 등）를 나타냅니다. curl은 기본적으로 HTTP 오류도 exit code 0（성공）으로 처리하므로 둘을 혼동하지 않도록 주의해야 합니다.
curl -f（--fail） 옵션을 추가하면 HTTP 응답이 400번대 이상일 때 exit code 22를 반환하게 됩니다. 추가하지 않으면 오류 페이지를 정상적으로 받아온 것만으로 exit code는 0이 되어 버립니다.6（COULDNT_RESOLVE_HOST）은 DNS 단계에서 호스트명을 IP 주소로 변환하지 못한 오류이고, 7（COULDNT_CONNECT）은 이름 확인에는 성공했지만 그 IP 주소로의 TCP 연결 수립에 실패한 오류입니다.
여담 ― curl exit code 체계
curl은 1996년 Daniel Stenberg가 개발을 시작한 명령줄 도구로, 처음에는 「httpget」이라는 이름이었습니다. 오늘날 curl은 사실상 모든 Linux 배포판・macOS・Windows 10 이후 버전에 기본으로 탑재되어 있으며, 웹 개발자에게 가장 기본적인 도구 중 하나가 되었습니다.
exit code 체계는 libcurl의 내부 오류 열거형인 CURLcode와 그대로 대응하며, `CURLE_OK`（성공, exit code 0）부터 시작하는 연번으로 정의되어 있습니다. 번호가 중간중간 비어 있는 것은 개발 과정에서 폐지되거나 통합된 오류 코드가 있기 때문입니다.
흥미롭게도 curl의 exit code는 POSIX의 일반적인 관례（0=성공, 1=일반 오류）와는 독립된 고유한 체계를 가지고 있습니다. 따라서 셸 스크립트에서 여러 명령의 exit code를 종합적으로 다룰 때는 각 도구의 매뉴얼에서 의미를 개별적으로 확인해야 합니다.