curl exit code 一覧・リファレンス｜番号や return code から検索（全コード対応）
curl の exit code・return code（終了コード、1〜99）を番号から検索できるリファレンス。exit code 22・3・28・52 など全コードの意味・よくある原因・対処法を掲載。公式ドキュメント代わりに使える、CI/CDやcronのエラー調査向けまとめ。
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 | 指定したプロキシサーバーのホスト名解決に失敗したことを示す。 | --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が失敗したときの原因調査に使うことを想定しています。
curl exit code の調べ方
-
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 を付けましょう。
curl exit code が役立つ場面
CI/CDパイプラインの失敗調査
ビルドログに記録されたexit codeを検索するだけで、curlを使ったデプロイやヘルスチェックが失敗した原因を素早く特定できます。
cronジョブの原因調査
cronジョブは出力が残らないことが多いため、ログに記録されたexit codeを確認するのが原因特定の最速の手段になることが多いです。
シェルスクリプトのエラー処理設計
リトライすべき一時的なネットワークエラーと、リトライしても解決しない恒久的なエラーを見分けて、スクリプトの分岐処理を設計できます。
障害発生後の事後調査（ポストモーテム）
障害対応後にログを見直す際、DNS・TLS・タイムアウトのどの種類の失敗だったかを正確に確認できます。
用語集
- exit code（終了コード）
- プログラム終了時にシェルへ返す番号です。0は成功を意味し、curlは1〜99で失敗の種類を表します。
- CURLcode
- libcurl内部で各エラー種別を定義するenum（列挙型）です。curlコマンドラインのexit codeはこのenumに直接対応しています。
- libcurl
- curlの転送処理の中核を実装しているCライブラリです。curlコマンドラインツールはこのライブラリの薄いラッパーです。
- --fail / -f オプション
- HTTPのエラー応答（400番台以上）が返ったときに、既定のexit code 0ではなくexit code 22を返すようにするcurlのオプションです。
- タイムアウトと接続拒否の違い
- タイムアウト（28）は時間内に応答が来なかったことを、接続拒否・失敗（7）はTCP接続自体を確立できなかったことを意味します。
よくある質問
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 以降に標準搭載されており、Web 開発者にとって最も基本的なツールの一つになっています。
exit code の体系は libcurl の内部エラー列挙型 CURLcode にそのまま対応しており、`CURLE_OK`（成功、exit code 0）から始まる連番で定義されています。欠番があるのは、開発の過程で非推奨・統合されたエラーコードが存在するためです。
興味深いことに、curl の exit code は POSIX の一般的な慣習（0=成功、1=一般エラー）とは独立した独自の体系を持っています。そのため、シェルスクリプトで複数のコマンドの exit code を横断的に扱う場合は、各ツールのマニュアルで意味を個別に確認する必要があります。