curl エラーコード：完全リファレンス

クイックリファレンス表

エラー 6: ホストを解決できませんでした

意味

ターミナルに curl: (6) Could not resolve host と表示されます。curl がホスト名を IP アドレスに解決できませんでした。接続を試行する前に DNS ルックアップが失敗しています。

原因

主な原因は、ホスト名の入力ミス（例：curl https://apiexample.com ではなく api.example.com）、DNS サーバーの問題（設定された DNS がダウンしているか到達不能）、ネットワーク接続なし（Wi-Fi や VPN の切断）、またはドメインが実際に存在しないことです。

修正方法

まず、URL が正しいか確認してください。次に、nslookup api.example.com や dig api.example.com を使用して DNS 解決を直接テストします。DNS が失敗する場合は、別の DNS サーバーを試してください：curl --dns-servers 8.8.8.8 https://api.example.com。/etc/resolv.conf やネットワーク設定を確認してください。社内 VPN を使用している場合は、内部 DNS がホストを解決できるか確認してください。

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

エラー 7: 接続に失敗しました

意味

ターミナルに curl: (7) Failed to connect to host port: Connection refused と表示されます。curl はホスト名を解決しましたが、サーバーへの TCP 接続を確立できませんでした。接続が明示的に拒否されたか、TCP レベルでタイムアウトしました。

原因

一般的な原因には、サーバーがダウンしている、ファイアウォールがポートをブロックしている（ローカルとサーバー側の両方を確認）、ポート番号が間違っている（例：サービスは 8080 で動作しているが 443 に接続している）、または高負荷によりサーバーの listen バックログがいっぱいになっていることが挙げられます。

修正方法

サーバーが動作しているか確認してください：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

エラー 22: HTTP エラーが返されました

意味

ターミナルに curl: (22) The requested URL returned error と表示されます。サーバーが HTTP エラーステータスコード（4xx または 5xx）を返し、curl が -f または --fail オプション付きで実行されました。これにより、curl は HTTP エラーを失敗として扱います。

原因

このエラーは、400 (Bad Request)、401 (Unauthorized)、403 (Forbidden)、404 (Not Found)、500 (Internal Server Error) などの HTTP ステータスコードによって発生しますが、--fail が使用されている場合に限ります。--fail がない場合、curl は HTTP エラーが発生しても終了コード 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

エラー 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

エラー 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 を最新バージョンに更新してください。サーバーが自己署名証明書を使用している場合、通常はエラー 60 になります。エラー 35 は通常、プロトコルレベルのハンドシェイク失敗を示します。

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

エラー 56: 受信失敗 — 接続がリセットされました

意味

ターミナルに curl: (56) Recv failure: Connection reset by peer と表示されます。接続は正常に確立されましたが、データの受信に失敗しました。転送中にサーバーが予期せず接続を閉じたか、リセットしました。

原因

これは多くの場合、サーバーが転送途中でクラッシュまたは再起動した、ロードバランサーやプロキシが接続を切断した（アイドルタイムアウト、リクエストが大きすぎる）、ファイアウォールが長時間接続を終了させた、サーバーの keep-alive タイムアウトが想定より短い、またはクライアントとサーバー間のネットワーク障害が発生したときに起こります。

修正方法

リクエストを再試行してください。一時的なネットワークの問題が最も一般的な原因です。詳細モード curl -v URL を使用して、失敗した正確なポイントを確認してください。大容量のアップロード中にエラーが発生する場合は、チャンク転送を試してください：curl -H "Transfer-Encoding: chunked" URL。RPC failed; curl 56 と表示される Git 操作の場合は、バッファを増やしてください：git config http.postBuffer 524288000。

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

エラー 60: SSL 証明書の問題

意味

ターミナルに curl: (60) SSL certificate problem: unable to get local issuer certificate と表示されます。curl が CA（認証局）バンドルに対してサーバーの SSL 証明書を検証できませんでした。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

その他のエラーコード

curlエラーのデバッグ方法

curlが失敗した際、DNS解決からSSLハンドシェイク、レスポンスペイロードに至るまで、これら3つのフラグが根本原因を素早く特定するのに役立ちます。

1. 1

   詳細出力（verbose）を有効にする

   curl -v URL を実行して、DNS解決、TCP接続、TLSハンドシェイク、送信されたリクエストヘッダー、受信したレスポンスヘッダーなど、リクエスト/レスポンスの全サイクルを確認します。これは最も有用なデバッグフラグです。

2. 2

   HTTPステータスコードを確認する

   curl -o /dev/null -s -w "%{http_code}" URL を実行すると、レスポンスボディを除いたHTTPステータスコード（200、404、500など）のみを取得できます。クイックなヘルスチェックやスクリプト作成に便利です。

3. 3

   エラーのみをサイレントに表示する

   curl -sS URL を実行して、プログレスバーを抑制し（-s）、エラーのみを表示（-S）させます。クリーンな出力を求めつつ、失敗をキャッチする必要があるスクリプトに最適です。

よくある質問