curl exit code・return code 목록(1-99): 번호로 찾는 의미와 해결법

curl exit code・return code(종료 코드, 1~99)를 번호로 검색합니다. 22・3・28・52 등 코드별 의미・흔한 원인・구체적인 해결 방법을 확인할 수 있는 개발자용 레퍼런스로, 공식 문서 대신 빠르게 참고할 수 있습니다. CI/CD・cron・셸 스크립트 디버깅에 유용합니다.

마지막 업데이트: 2026-09-03

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회）을 넘는 정상적인 리다이렉트 체인에서 발생합니다.

curl exit code란?

curl exit code(종료 코드)는 curl 명령어가 실행을 마쳤을 때 셸에 반환하는 번호로, $?로 확인할 수 있으며 요청이 성공했는지, 실패했다면 그 원인이 무엇인지를 나타냅니다. 서버가 반환하는 HTTP 상태 코드와 달리 exit code는 DNS 실패・연결 타임아웃・SSL 핸드셰이크 오류 등 curl 명령어 자체의 실행 결과를 나타냅니다.

이 도구는 코드 번호(1~99)를 입력하면 의미와 흔한 원인을 바로 확인할 수 있고, 코드 번호・상수명・키워드로 전체 목록을 필터링할 수도 있습니다. CI/CD 파이프라인・cron 작업・셸 스크립트에서 curl이 API 호출이나 파일 다운로드 중 실패했을 때 원인을 조사하는 용도로 사용할 수 있습니다.

사용 방법

exit code 번호를 입력합니다 curl 명령어 실패 후 echo $?로 확인한 번호를 검색창에 입력합니다.
의미와 흔한 원인을 확인합니다 해당 코드가 나타내는 내용과 일반적으로 발생하는 상황이 표시됩니다.
전체 목록에서 필터링해 찾습니다 정확한 번호를 모를 경우 목록을 키워드로 필터링해 해당 코드를 찾을 수 있습니다.
제안된 해결 방법을 확인합니다 흔한 원인을 참고해 스크립트나 환경에 맞는 수정 방법을 적용합니다.

더 잘 활용하기 위한 팁

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를 붙이세요.

활용 사례

CI/CD 파이프라인 실패 원인 조사

빌드 로그에 기록된 exit code를 검색하는 것만으로 curl 기반 배포나 헬스체크 단계가 실패한 원인을 빠르게 파악할 수 있습니다.

cron 작업의 조용한 실패 진단

cron 작업은 출력이 남지 않는 경우가 많아, 로그에 기록된 exit code를 확인하는 것이 원인 파악의 가장 빠른 방법인 경우가 많습니다.

셸 스크립트의 안정적인 오류 처리 설계

재시도할 가치가 있는 일시적 네트워크 오류와 재시도해도 해결되지 않는 영구적 오류를 구분해 스크립트의 분기 로직을 설계할 수 있습니다.

장애 발생 후 사후 분석(포스트모템)

장애 대응 후 로그를 검토할 때 DNS・TLS・타임아웃 중 어떤 유형의 실패였는지 정확히 확인할 수 있습니다.

curl과 네트워크 기초 학습

목록을 참고해 전송의 어느 단계(이름 해석・연결・TLS・전송)에서 오류가 발생할 수 있는지 체계적으로 이해할 수 있습니다.

용어집

exit code(종료 코드): 프로그램이 종료될 때 셸에 반환하는 번호입니다. 0은 성공을 의미하며, curl은 1~99로 실패 유형을 나타냅니다.
CURLcode: libcurl 내부에서 각 오류 종류를 정의하는 열거형(enum)입니다. curl 명령줄의 exit code는 이 열거형에 직접 대응합니다.
libcurl: curl의 전송 처리 핵심을 구현한 C 라이브러리입니다. curl 명령줄 도구는 이 라이브러리를 얇게 감싼 것에 불과합니다.
--fail / -f 옵션: HTTP 오류 응답(400번대 이상)이 반환되었을 때 기본값인 exit code 0 대신 exit code 22를 반환하도록 하는 curl 옵션입니다.
타임아웃과 연결 거부의 차이: 타임아웃(28)은 제한 시간 내에 응답이 오지 않은 것을, 연결 거부・실패(7)는 TCP 연결 자체를 맺지 못한 것을 의미합니다.
DNS 이름 해석: 호스트명을 IP 주소로 변환하는 과정입니다. 이 과정이 실패하면 curl은 exit code 6을 반환합니다.
SSL/TLS 핸드셰이크: 클라이언트와 서버가 암호화된 연결을 맺는 과정입니다. 이 단계의 문제는 보통 exit code 35・51・58・60으로 나타납니다.

자주 묻는 질문

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를 종합적으로 다룰 때는 각 도구의 매뉴얼에서 의미를 개별적으로 확인해야 합니다.

모든 여담 보기