curl 오류 코드: 완전 레퍼런스

Q: curl 종료 코드는 어떻게 확인하나요?

curl 명령어를 실행한 후, 종료 코드는 셸의 특수 변수에 저장됩니다. Bash/Zsh에서는 curl 명령어 직후에 echo $?를 실행하세요. PowerShell에서는 $LASTEXITCODE를 사용하세요. 스크립트에서는 조건문으로 확인할 수 있습니다: if curl -sf URL; then echo "OK"; else echo "Failed with code $?"; fi. 종료 코드 0은 성공을 의미하며, 다른 숫자는 오류를 나타냅니다. HTTP 상태 코드와 curl 종료 코드를 모두 보려면 curl -w "%{http_code}" -o /dev/null -s URL; echo "Exit: $?"를 결합하세요. curl의 종료 코드는 HTTP 상태 코드와 다릅니다 — --fail 플래그를 사용하지 않으면 HTTP 404에서도 curl은 0을 반환합니다.

Q: curl error 28 (작업 시간 초과)을 어떻게 수정하나요?

Error 28은 요청이 최대 허용 시간을 초과했음을 의미합니다. 먼저 타임아웃을 늘리세요: curl --connect-timeout 30 --max-time 120 URL. --connect-timeout은 TCP 연결 단계를 제한하고, --max-time은 전체 작업을 제한합니다. 다음으로 curl -v URL로 병목 현상을 진단하세요 — 자세한 출력은 curl이 정확히 어디서(DNS, 연결, TLS 또는 전송) 멈추는지 보여줍니다. 일반적인 수정 방법: 네트워크 연결 및 DNS 설정 확인, 서버가 응답하는지 확인(ping 및 telnet), --noproxy '*'로 프록시 우회, 대용량 다운로드에는 자동 재시도를 위해 --retry 3 --retry-delay 5 추가.

curl 명령어가 실패하면, 오류 유형을 식별하는 숫자 종료 코드(curl 오류 코드라고도 함)를 반환합니다. curl 종료 코드는 curl 명령어 직후에 echo $?를 실행하여(PowerShell에서는 $LASTEXITCODE) 확인할 수 있습니다. 종료 코드 0은 성공을 의미하며, 그 외의 숫자는 DNS 해석 실패, 연결 타임아웃, SSL 인증서 문제 등 특정 문제를 나타냅니다. 이 페이지는 가장 일반적인 curl 오류 코드에 대한 설명, 원인 및 수정 방법을 포함한 완전한 레퍼런스입니다. 코드에서 curl 명령어를 사용하고 계시다면, curl2code에 붙여넣어 원하는 프로그래밍 언어로 변환하세요.

빠른 참조 표

종료 코드	오류 이름	설명
0	CURLE_OK	성공. 작업이 오류 없이 완료되었습니다.
1	CURLE_UNSUPPORTED_PROTOCOL	지원되지 않는 프로토콜. URL이 curl이 지원하도록 빌드되지 않은 프로토콜을 사용합니다.
3	CURLE_URL_MALFORMAT	잘못된 URL 형식. URL 구문이 유효하지 않거나 파싱할 수 없습니다.
5	CURLE_COULDNT_RESOLVE_PROXY	프록시를 해석할 수 없음. 지정된 프록시 호스트 이름을 해석할 수 없습니다.
6	CURLE_COULDNT_RESOLVE_HOST	DNS 조회 실패 — 호스트 이름을 IP 주소로 해석할 수 없습니다.
7	CURLE_COULDNT_CONNECT	TCP 연결 실패 — 서버가 다운되었거나, 포트가 차단되었거나, 방화벽이 연결을 거부합니다.
18	CURLE_PARTIAL_FILE	불완전한 파일. 전송이 중단되어 파일의 일부만 수신되었습니다.
22	CURLE_HTTP_RETURNED_ERROR	서버가 HTTP 오류(4xx/5xx)를 반환했으며 --fail 플래그가 사용되었습니다.
23	CURLE_WRITE_ERROR	쓰기 오류. curl이 수신한 데이터를 디스크에 쓰지 못했습니다(권한 거부 또는 디스크 가득 참).
28	CURLE_OPERATION_TIMEDOUT	작업이 최대 허용 시간을 초과했습니다(DNS, 연결 또는 전송).
35	CURLE_SSL_CONNECT_ERROR	SSL/TLS 핸드셰이크 실패 — 프로토콜 버전 또는 암호 스위트 불일치.
37	CURLE_FILE_COULDNT_READ_FILE	파일을 읽을 수 없음. 요청에서 참조된 로컬 파일을 열거나 읽을 수 없습니다.
52	CURLE_GOT_NOTHING	서버로부터 빈 응답. 서버가 데이터를 보내지 않고 연결을 닫았습니다.
56	CURLE_RECV_ERROR	연결이 리셋됨 — 데이터 전송 중 서버가 연결을 끊었습니다.
60	CURLE_SSL_CACERT	SSL 인증서 검증 실패 — 만료됨, 자체 서명됨 또는 CA 번들이 오래되었습니다.
77	CURLE_SSL_CACERT_BADFILE	SSL CA 인증서 문제. 지정된 CA 인증서 파일을 읽거나 파싱할 수 없습니다.
92	CURLE_HTTP2_STREAM	HTTP/2 스트림 오류. 전송 중 HTTP/2 프로토콜 수준의 스트림 오류가 발생했습니다.

0CURLE_OK

성공. 작업이 오류 없이 완료되었습니다.

1CURLE_UNSUPPORTED_PROTOCOL

지원되지 않는 프로토콜. URL이 curl이 지원하도록 빌드되지 않은 프로토콜을 사용합니다.

3CURLE_URL_MALFORMAT

잘못된 URL 형식. URL 구문이 유효하지 않거나 파싱할 수 없습니다.

5CURLE_COULDNT_RESOLVE_PROXY

프록시를 해석할 수 없음. 지정된 프록시 호스트 이름을 해석할 수 없습니다.

6CURLE_COULDNT_RESOLVE_HOST

DNS 조회 실패 — 호스트 이름을 IP 주소로 해석할 수 없습니다.

7CURLE_COULDNT_CONNECT

TCP 연결 실패 — 서버가 다운되었거나, 포트가 차단되었거나, 방화벽이 연결을 거부합니다.

18CURLE_PARTIAL_FILE

불완전한 파일. 전송이 중단되어 파일의 일부만 수신되었습니다.

22CURLE_HTTP_RETURNED_ERROR

서버가 HTTP 오류(4xx/5xx)를 반환했으며 --fail 플래그가 사용되었습니다.

23CURLE_WRITE_ERROR

쓰기 오류. curl이 수신한 데이터를 디스크에 쓰지 못했습니다(권한 거부 또는 디스크 가득 참).

28CURLE_OPERATION_TIMEDOUT

작업이 최대 허용 시간을 초과했습니다(DNS, 연결 또는 전송).

35CURLE_SSL_CONNECT_ERROR

SSL/TLS 핸드셰이크 실패 — 프로토콜 버전 또는 암호 스위트 불일치.

37CURLE_FILE_COULDNT_READ_FILE

파일을 읽을 수 없음. 요청에서 참조된 로컬 파일을 열거나 읽을 수 없습니다.

52CURLE_GOT_NOTHING

서버로부터 빈 응답. 서버가 데이터를 보내지 않고 연결을 닫았습니다.

56CURLE_RECV_ERROR

연결이 리셋됨 — 데이터 전송 중 서버가 연결을 끊었습니다.

60CURLE_SSL_CACERT

SSL 인증서 검증 실패 — 만료됨, 자체 서명됨 또는 CA 번들이 오래되었습니다.

77CURLE_SSL_CACERT_BADFILE

SSL CA 인증서 문제. 지정된 CA 인증서 파일을 읽거나 파싱할 수 없습니다.

92CURLE_HTTP2_STREAM

HTTP/2 스트림 오류. 전송 중 HTTP/2 프로토콜 수준의 스트림 오류가 발생했습니다.

Error 6: 호스트를 해석할 수 없음

의미: 터미널에 curl: (6) Could not resolve host가 표시됩니다. curl이 호스트 이름을 IP 주소로 해석할 수 없습니다 — 연결을 시도하기 전에 DNS 조회가 실패했습니다.
원인: 가장 일반적인 원인은: 호스트 이름의 오타(예: api.example.com 대신 curl https://apiexample.com), DNS 서버 문제(설정된 DNS가 다운되었거나 접근 불가), 네트워크 연결 없음(Wi-Fi 연결 끊김, VPN 미연결), 또는 도메인이 실제로 존재하지 않는 경우입니다.
수정 방법: 먼저 URL이 올바른지 확인하세요. 그런 다음 DNS 해석을 직접 테스트하세요: nslookup api.example.com 또는 dig api.example.com. DNS가 실패하면 다른 DNS 서버를 시도하세요: curl --dns-servers 8.8.8.8 https://api.example.com. /etc/resolv.conf 또는 네트워크 설정을 확인하세요. 회사 VPN 뒤에 있다면, 내부 DNS가 해당 호스트를 해석할 수 있는지 확인하세요.

$ curl https://api.exmple.com/users

Error 7: 연결 실패

의미: 터미널에 curl: (7) Failed to connect to host port: Connection refused가 표시됩니다. curl이 호스트 이름을 해석했지만 서버에 TCP 연결을 설정할 수 없습니다 — TCP 수준에서 연결이 거부되었거나 시간 초과되었습니다.
원인: 일반적인 원인: 서버가 다운되었거나 실행 중이 아님, 방화벽이 포트를 차단(로컬 및 서버 측 방화벽 모두 확인), 포트가 잘못됨(예: 서비스가 8080에서 실행되지만 443에 연결하는 경우), 또는 서버의 리슨 백로그가 가득 찬 경우(높은 부하).
수정 방법: 서버가 실행 중인지 확인하세요: ping api.example.com 및 telnet api.example.com 443. 올바른 포트가 열려 있는지 확인하세요: nmap -p 443 api.example.com. 테스트를 위해 로컬 방화벽을 일시적으로 비활성화하세요. Docker를 사용하는 경우 컨테이너 포트가 퍼블리시되었는지 확인하세요. 자세한 모드를 사용해 보세요: curl -v https://api.example.com으로 정확히 어디서 연결이 실패하는지 확인하세요.

$ curl https://localhost:8080/api

Error 22: HTTP가 오류를 반환함

의미: 터미널에 curl: (22) The requested URL returned error가 표시됩니다. 서버가 HTTP 오류 상태 코드(4xx 또는 5xx)를 반환했으며, curl이 HTTP 오류를 실패로 처리하도록 -f 또는 --fail과 함께 호출되었습니다.
원인: 이 오류는 400(Bad Request), 401(Unauthorized), 403(Forbidden), 404(Not Found), 500(Internal Server Error)과 같은 HTTP 상태 코드에 의해 발생합니다 — 단, --fail이 사용된 경우에만 해당됩니다. --fail 없이는 HTTP 오류가 발생해도 curl은 코드 0으로 종료합니다. 일반적인 원인: 잘못된 URL, 인증 누락, 권한 부족 또는 서버 측 버그.
수정 방법: --fail 없이 curl을 실행하여 전체 응답 본문을 확인하세요 — 실제 오류 메시지가 포함되어 있는 경우가 많습니다. HTTP 상태 코드를 확인하세요: curl -w "%{http_code}" -o /dev/null -s URL. 401/403의 경우: 인증 토큰 또는 API 키를 확인하세요. 404의 경우: URL 경로를 다시 확인하세요. 500의 경우: 문제는 서버 측에 있습니다.

$ curl --fail https://api.example.com/nonexistent

Error 28: 작업 시간 초과

의미: 터미널에 curl: (28) Operation timed out 또는 curl: (28) Connection timed out가 표시됩니다. 작업이 허용된 시간보다 오래 걸렸습니다. 이것은 가장 일반적인 curl 오류로, DNS 해석, TCP 연결, SSL 핸드셰이크, 데이터 전송 중에 발생할 수 있습니다.
원인: 일반적인 원인: 느리거나 과부하된 서버가 시간 내에 응답하지 않음, 네트워크 혼잡 또는 패킷 손실, 방화벽이 패킷을 조용히 드롭(거부 없이 침묵), --connect-timeout 또는 --max-time으로 설정된 지나치게 엄격한 타임아웃 값, 또는 프록시 설정 오류로 인한 지연.
수정 방법: 타임아웃을 늘리세요: curl --connect-timeout 30 --max-time 120 URL. 자세한 모드를 사용하여 어디서 멈추는지 확인하세요: curl -v URL. 네트워크 지연 시간을 테스트하세요: ping api.example.com 및 traceroute api.example.com. 프록시 뒤에 있다면, 우회를 시도하세요: curl --noproxy '*' URL. 대용량 파일 전송의 경우, --retry 3과 --retry-delay 5를 사용하는 것을 고려하세요.

$ curl --connect-timeout 5 https://slow-api.example.com/data

Error 35: SSL 연결 오류

의미: 터미널에 curl: (35) SSL connect error가 표시됩니다. SSL/TLS 핸드셰이크가 실패했습니다 — curl이 서버와 보안 연결을 설정할 수 없었습니다.
원인: 일반적인 원인: TLS 버전 불일치(서버가 TLS 1.3을 요구하지만 curl이 TLS 1.2까지만 지원), 암호 스위트 비호환, 서버 SSL 설정 오류(핸드셰이크 중 만료된 인증서 제시, 불완전한 체인), 서버가 해당 포트에서 실제로 HTTPS를 지원하지 않는 경우, 또는 프록시나 방화벽이 SSL 연결을 가로채는 경우(MITM).
수정 방법: 특정 TLS 버전을 강제하세요: curl --tlsv1.2 URL 또는 curl --tlsv1.3 URL. 서버가 무엇을 지원하는지 확인하세요: openssl s_client -connect api.example.com:443. curl과 OpenSSL을 최신 버전으로 업데이트하세요. 서버가 자체 서명 인증서를 사용하는 경우, 이는 보통 error 60입니다 — error 35는 일반적으로 프로토콜 수준의 핸드셰이크 실패를 나타냅니다.

$ curl https://legacy-server.example.com/api

Error 56: 수신 실패 — 연결이 리셋됨

의미: 터미널에 curl: (56) Recv failure: Connection reset by peer가 표시됩니다. 연결은 성공적으로 설정되었지만, 데이터 수신이 실패했습니다 — 전송 중에 서버가 예기치 않게 연결을 닫거나 리셋했습니다.
원인: 이는 종종 다음과 같은 경우에 발생합니다: 서버가 전송 중 충돌하거나 재시작, 로드 밸런서 또는 프록시가 연결을 끊음(유휴 타임아웃, 요청 크기 초과), 방화벽이 장기 연결을 종료, 서버의 keep-alive 타임아웃이 예상보다 짧은 경우, 또는 클라이언트와 서버 사이의 네트워크 중단.
수정 방법: 요청을 다시 시도하세요 — 일시적인 네트워크 문제가 가장 일반적인 원인입니다. 자세한 모드를 사용하세요: curl -v URL으로 정확한 실패 지점을 확인하세요. 대용량 업로드 중 오류가 발생하면 청크 전송을 시도하세요: curl -H "Transfer-Encoding: chunked" URL. Git 작업에서 RPC failed; curl 56이 표시되면, 버퍼를 늘리세요: git config http.postBuffer 524288000.

$ curl https://api.example.com/large-download

Error 60: SSL 인증서 문제

의미: 터미널에 curl: (60) SSL certificate problem: unable to get local issuer certificate가 표시됩니다. curl이 서버의 SSL 인증서를 CA(인증 기관) 번들에 대해 확인할 수 없었습니다. TLS 핸드셰이크는 프로토콜 수준에서 완료되었지만, 인증서 검증이 실패했습니다.
원인: 가장 일반적인 원인: 서버가 자체 서명 인증서를 사용, 인증서가 만료됨, 인증서 체인이 불완전(중간 인증서 누락), curl의 CA 번들이 오래됨(이전 시스템이나 Docker 컨테이너에서 흔함), 또는 인증서의 Common Name / SAN이 요청된 호스트 이름과 일치하지 않는 경우.
수정 방법: CA 번들을 업데이트하세요: curl --cacert /path/to/cacert.pem URL. https://curl.se/ca/cacert.pem에서 업데이트된 번들을 다운로드하세요. 진단하려면: openssl s_client -connect api.example.com:443 -showcerts. 개발 환경의 자체 서명 인증서의 경우, curl -k URL을 사용하세요(프로덕션에서는 절대 사용하지 마세요 — 모든 인증서 검증을 비활성화합니다). Docker에서는 ca-certificates 패키지를 설치하세요.

$ curl https://self-signed.example.com/api

기타 오류 코드

종료 코드	오류 이름	설명
0	CURLE_OK	성공. 작업이 오류 없이 완료되었습니다.
1	CURLE_UNSUPPORTED_PROTOCOL	지원되지 않는 프로토콜. URL이 curl이 지원하도록 빌드되지 않은 프로토콜을 사용합니다.
3	CURLE_URL_MALFORMAT	잘못된 URL 형식. URL 구문이 유효하지 않거나 파싱할 수 없습니다.
5	CURLE_COULDNT_RESOLVE_PROXY	프록시를 해석할 수 없음. 지정된 프록시 호스트 이름을 해석할 수 없습니다.
18	CURLE_PARTIAL_FILE	불완전한 파일. 전송이 중단되어 파일의 일부만 수신되었습니다.
23	CURLE_WRITE_ERROR	쓰기 오류. curl이 수신한 데이터를 디스크에 쓰지 못했습니다(권한 거부 또는 디스크 가득 참).
37	CURLE_FILE_COULDNT_READ_FILE	파일을 읽을 수 없음. 요청에서 참조된 로컬 파일을 열거나 읽을 수 없습니다.
52	CURLE_GOT_NOTHING	서버로부터 빈 응답. 서버가 데이터를 보내지 않고 연결을 닫았습니다.
77	CURLE_SSL_CACERT_BADFILE	SSL CA 인증서 문제. 지정된 CA 인증서 파일을 읽거나 파싱할 수 없습니다.
92	CURLE_HTTP2_STREAM	HTTP/2 스트림 오류. 전송 중 HTTP/2 프로토콜 수준의 스트림 오류가 발생했습니다.

0CURLE_OK

성공. 작업이 오류 없이 완료되었습니다.

1CURLE_UNSUPPORTED_PROTOCOL

지원되지 않는 프로토콜. URL이 curl이 지원하도록 빌드되지 않은 프로토콜을 사용합니다.

3CURLE_URL_MALFORMAT

잘못된 URL 형식. URL 구문이 유효하지 않거나 파싱할 수 없습니다.

5CURLE_COULDNT_RESOLVE_PROXY

프록시를 해석할 수 없음. 지정된 프록시 호스트 이름을 해석할 수 없습니다.

18CURLE_PARTIAL_FILE

불완전한 파일. 전송이 중단되어 파일의 일부만 수신되었습니다.

23CURLE_WRITE_ERROR

쓰기 오류. curl이 수신한 데이터를 디스크에 쓰지 못했습니다(권한 거부 또는 디스크 가득 참).

37CURLE_FILE_COULDNT_READ_FILE

파일을 읽을 수 없음. 요청에서 참조된 로컬 파일을 열거나 읽을 수 없습니다.

52CURLE_GOT_NOTHING

서버로부터 빈 응답. 서버가 데이터를 보내지 않고 연결을 닫았습니다.

77CURLE_SSL_CACERT_BADFILE

SSL CA 인증서 문제. 지정된 CA 인증서 파일을 읽거나 파싱할 수 없습니다.

92CURLE_HTTP2_STREAM

HTTP/2 스트림 오류. 전송 중 HTTP/2 프로토콜 수준의 스트림 오류가 발생했습니다.

curl 오류를 디버깅하는 방법

curl이 실패하면, 이 세 가지 플래그가 DNS 해석부터 SSL 핸드셰이크, 응답 페이로드까지 근본 원인을 빠르게 식별하는 데 도움됩니다.

1
자세한 출력 활성화
curl -v URL을 실행하여 전체 요청/응답 사이클을 확인하세요: DNS 해석, TCP 연결, TLS 핸드셰이크, 전송된 요청 헤더, 수신된 응답 헤더. 이것이 가장 유용한 디버깅 플래그입니다.
2
HTTP 상태 코드 확인
curl -o /dev/null -s -w "%{http_code}" URL을 실행하여 응답 본문 없이 HTTP 상태 코드(200, 404, 500 등)만 가져오세요. 빠른 상태 확인과 스크립팅에 유용합니다.
3
오류만 조용히 표시
curl -sS URL을 실행하여 진행률 표시줄을 숨기되(-s) 오류는 표시합니다(-S). 깔끔한 출력을 원하면서도 실패를 잡아야 하는 스크립트에 적합합니다.

자주 묻는 질문

curl 종료 코드는 어떻게 확인하나요?

curl 명령어를 실행한 후, 종료 코드는 셸의 특수 변수에 저장됩니다. Bash/Zsh에서는 curl 명령어 직후에 echo $?를 실행하세요. PowerShell에서는 $LASTEXITCODE를 사용하세요. 스크립트에서는 조건문으로 확인할 수 있습니다: if curl -sf URL; then echo "OK"; else echo "Failed with code $?"; fi. 종료 코드 0은 성공을 의미하며, 다른 숫자는 오류를 나타냅니다. HTTP 상태 코드와 curl 종료 코드를 모두 보려면 curl -w "%{http_code}" -o /dev/null -s URL; echo "Exit: $?"를 결합하세요. curl의 종료 코드는 HTTP 상태 코드와 다릅니다 — --fail 플래그를 사용하지 않으면 HTTP 404에서도 curl은 0을 반환합니다.

curl error 28 (작업 시간 초과)을 어떻게 수정하나요?

Error 28은 요청이 최대 허용 시간을 초과했음을 의미합니다. 먼저 타임아웃을 늘리세요: curl --connect-timeout 30 --max-time 120 URL. --connect-timeout은 TCP 연결 단계를 제한하고, --max-time은 전체 작업을 제한합니다. 다음으로 curl -v URL로 병목 현상을 진단하세요 — 자세한 출력은 curl이 정확히 어디서(DNS, 연결, TLS 또는 전송) 멈추는지 보여줍니다. 일반적인 수정 방법: 네트워크 연결 및 DNS 설정 확인, 서버가 응답하는지 확인(ping 및 telnet), --noproxy '*'로 프록시 우회, 대용량 다운로드에는 자동 재시도를 위해 --retry 3 --retry-delay 5 추가.

curl SSL 인증서 오류(error 60)를 어떻게 수정하나요?

Error 60은 curl이 서버의 SSL 인증서를 확인할 수 없음을 의미합니다. 수정 방법은 원인에 따라 다릅니다. 오래된 CA 번들의 경우: https://curl.se/ca/cacert.pem에서 새 번들을 다운로드하고 curl --cacert /path/to/cacert.pem URL을 사용하세요. Docker 컨테이너의 경우: ca-certificates 패키지를 설치하세요(apt-get install ca-certificates). 개발 환경의 자체 서명 인증서의 경우: curl -k URL을 사용하여 검증을 건너뛰세요 — 단 프로덕션에서는 절대 -k를 사용하지 마세요. 모든 인증서 확인을 비활성화합니다. 진단하려면: openssl s_client -connect host:443 -showcerts로 인증서 체인을 검사하세요. 인증서가 만료되었거나 호스트 이름이 일치하지 않으면, 문제는 서버 측에 있습니다.

curl error 7 (연결 실패)은 무엇을 의미하나요?

Error 7은 curl이 호스트 이름을 IP 주소로 해석했지만 TCP 연결을 설정할 수 없었음을 의미합니다. 서버가 연결을 적극적으로 거부했거나 네트워크 수준에서 연결 시도가 시간 초과되었습니다. 일반적인 원인: 대상 호스트에서 서비스가 실행되지 않음(systemctl status 또는 docker ps로 확인), 방화벽이 포트를 차단(telnet host port로 테스트), 잘못된 포트 사용(예: 443 대신 80, 또는 개발 서버의 8080), 또는 높은 부하로 서버의 리슨 백로그가 가득 찬 경우. 디버깅하려면: curl -v URL을 사용하고 출력에서 "Connected to" 또는 "Connection refused"를 찾으세요.