Cara Mengatur Batas Waktu dengan curl: Opsi, Contoh, dan Kesalahan

Sebuah penjelasan singkat sebelum kita membahas perintah-perintahnya: kami adalah Geonode dan kami menjual layanan proxy; artinya, sejujurnya perlu disampaikan sejak awal bahwa timeout curl hampir tidak pernah disebabkan oleh masalah proxy. Jika permintaan Anda mengalami timeout terhadap server yang sekadar lambat, atau host yang sedang down, atau firewall yang memblokir paket tanpa pemberitahuan, mengarahkan permintaan melalui kami tidak akan mengubah apa pun kecuali tagihan Anda. Proksi berguna ketika masalahnya terletak pada dari mana permintaan Anda tampaknya berasal — konten yang dibatasi secara geografis, batasan laju yang didasarkan pada alamat Anda, atau alamat IP yang telah diblokir. Proksi tidak akan membuat server yang lambat menjadi cepat. Atur batas waktu Anda dengan benar terlebih dahulu; Anda mungkin menyadari bahwa Anda tidak memerlukan hal lain.

Benar. Inilah hal yang kebanyakan orang temukan dengan cara yang sulit: curl tidak memiliki batas waktu keseluruhan bawaan. Ia memiliki batas waktu koneksi bawaan sebesar 300 detik, tetapi begitu koneksi terjalin, curl akan dengan senang hati menunggu tanpa batas waktu untuk respons yang tidak pernah sepenuhnya tiba. Dalam skrip shell yang berjalan di cron, ini berarti tugas yang tidak pernah selesai dan berkas kunci yang tidak pernah dihapus oleh siapa pun.

Dua Batas Waktu yang Penting

Seluruh hal lainnya hanyalah penyempurnaan dari kedua hal ini.

--max-time

(bentuk singkat -m

) menjadi batas akhir dari seluruh proses. Dari panduan curl: "Waktu maksimum dalam detik yang Anda izinkan untuk proses transfer berlangsung." Mulai dari koneksi, handshake, permintaan, hingga respons—semuanya. Saat batas tersebut tercapai, curl akan menghentikan proses dan keluar dengan kode 28.

curl -m 10 https://example.com

Total sepuluh detik, kemudian curl akan berhenti terlepas dari tahap mana yang telah dicapai.

--connect-timeout

hanya membatasi fase penyiapan. Manual tersebut menjelaskan dengan tepat apa saja yang termasuk di dalamnya: "Fase koneksi dianggap selesai ketika pencarian DNS dan proses handshake TCP, TLS, atau QUIC yang diminta telah selesai." Setelah koneksi terjalin, opsi ini tidak berlaku lagi.

curl --connect-timeout 3 https://example.com

Tiga detik untuk menyelesaikan pencarian nama dan proses handshake. Setelah itu, curl akan menunggu selama waktu yang dibutuhkan untuk transfer.

Dalam praktiknya, Anda memerlukan keduanya, dan masing-masing menjawab pertanyaan yang berbeda:

Opsi	Mencakup	Nilai Umum	Melindungi dari
`--connect-timeout`

| Seluruh operasi | 10–60 detik, tergantung beban kerja | Respons lambat, transfer terhenti, aliran data tak berujung |

Secara keseluruhan:

curl --connect-timeout 5 -m 30 https://example.com

Lima detik untuk terhubung, tiga puluh detik untuk keseluruhan proses. Jika host tidak dapat dijangkau, Anda akan gagal dalam lima detik, bukan tiga puluh detik, yang sangat berpengaruh saat Anda mengiterasi daftar seribu URL.

Memilih Nilai yang Bukan Sekadar Tebakan

Pendekatan yang umum dilakukan adalah memilih angka bulat dan menaikkan nilainya setiap kali terjadi kegagalan. Hal ini akan mengarah pada nilai yang begitu besar sehingga batas waktu (timeout) tidak lagi berguna.

Metode yang lebih baik hanya memerlukan satu perintah tambahan. curl dapat melaporkan ke mana waktu tersebut sebenarnya terpakai:

curl -o /dev/null -s -w "dns: %{time_namelookup}\nconnect: %{time_connect}\ntls: %{time_appconnect}\nttfb: %{time_starttransfer}\ntotal: %{time_total}\n" https://example.com

Jalankan perintah tersebut terhadap target Anda yang sebenarnya sebanyak dua puluh atau tiga puluh kali, dan Anda akan mendapatkan distribusi, bukan sekadar tebakan. Kemudian:

Tetapkan --connect-timeout dari time_appconnect. Ambil nilai p95 dan kira-kira gandakan nilainya. Waktu koneksi didominasi oleh waktu bolak-balik jaringan dan relatif stabil; jika waktu yang dibutuhkan dua kali lipat dari biasanya, berarti ada masalah yang serius, bukan sekadar lambat.

Atur --max-time dari time_total. Di sini, faktor pengali sebaiknya lebih besar — tiga hingga lima kali nilai p95 — karena waktu total bergantung pada ukuran respons dan beban server, yang keduanya memang bervariasi. Nilai --max-time yang terlalu ketat akan menghasilkan skrip yang tidak stabil dan gagal pada hari-hari buruk biasa.

Dua penyesuaian khusus beban kerja. Jika Anda mengunduh file besar, --max-time sama sekali bukan alat yang tepat, karena unduhan yang sah dapat melebihi batas tetap yang wajar — gunakan opsi berbasis kecepatan di bawah ini sebagai gantinya. Dan jika Anda memanggil API yang melakukan pekerjaan nyata di sisi server, tanyakan berapa batas waktu (timeout) layanannya dan atur batas waktu Anda sedikit lebih tinggi; jika batas waktu Anda 10 detik sedangkan layanan tersebut mengembalikan respons dalam 12 detik, berarti Anda telah membayar biaya pemrosesan tetapi membuang hasilnya.

Desimal Detik dan Presisi Milidetik

Kedua opsi tersebut mendukung angka desimal, dengan menggunakan titik sebagai pemisah terlepas dari pengaturan wilayah Anda. Fitur ini telah didukung sejak curl 7.32.0.

curl --connect-timeout 0.5 -m 2.5 https://example.com

Setengah detik untuk terhubung, total dua setengah detik. Berguna untuk pemeriksaan kesehatan dan untuk loop apa pun di mana penundaan satu detik penuh per kegagalan akan bertambah.

Satu hal yang perlu diperhatikan: presisi akan menurun seiring bertambahnya nilai. Dokumentasi curl menyebutkan bahwa akurasi batas waktu aktual akan menurun seiring meningkatnya presisi desimal pada batas waktu yang ditentukan. Menulis --max-time 30.001 tidak jauh berbeda artinya dengan --max-time 30. Bilangan desimal digunakan untuk nilai di bawah satu detik; di atas beberapa detik, gunakan bilangan bulat.

Opsi terkait --expect100-timeout juga menerima nilai desimal. Opsi ini mengontrol berapa lama curl menunggu respons 100 Continue sebelum mengirim badan permintaan, dengan nilai default satu detik. Jika Anda mengirim badan permintaan besar melalui POST ke server yang tidak pernah mengirim 100 Continue, Anda akan menghabiskan satu detik pada setiap permintaan — kurangi nilainya atau nonaktifkan ekspektasi tersebut dengan -H "Expect:".

Mengatasi Transfer yang Terhenti dan Tidak Pernah Mencapai Batas Waktu

Inilah masalahnya. Transfer yang mengirimkan satu byte setiap beberapa detik tidak pernah dalam keadaan idle, sehingga batas waktu di tingkat koneksi tidak akan terpicu; dan jika nilai ``--max-time`

` diatur cukup tinggi untuk unduhan berukuran besar yang sah, batas waktu tersebut juga tidak akan terpicu. Permintaan tersebut hanya berjalan sangat lambat.

Opsi ``--speed-limit`

dan ``--speed-time

menangani hal ini. Dari manual: "Jika kecepatan unduhan lebih lambat dari ``--speed-limit

byte per detik selama periode ``--speed-time

`, transfer akan dibatalkan."

curl --speed-limit 1000 --speed-time 30 -O https://example.com/large-file.zip

Jika throughput tetap di bawah 1000 byte per detik selama 30 detik berturut-turut, curl akan membatalkan proses — sekali lagi dengan kode keluar 28. Unduhan yang berjalan selama enam jam dengan kecepatan yang stabil tidak akan terpengaruh. Unduhan yang terhenti akan dihentikan dalam waktu tiga puluh detik.

Ini adalah batas waktu yang tepat untuk apa pun yang ukurannya tidak dapat diprediksi, dan pola ini bekerja dengan baik:

curl --connect-timeout 5 --speed-limit 1000 --speed-time 30 -O https://example.com/large-file.zip

Kegagalan cepat pada host yang mati, tanpa batasan keseluruhan, tetapi dilengkapi dengan detektor kemacetan sepanjang proses. Khusus untuk pengunduhan berkas, pola ini harus ada di setiap skrip — lihat panduan kami tentang mengunduh berkas dengan curl untuk opsi-opsi terkait.

Batas Waktu dan Upaya Ulang Berinteraksi Buruk Secara Default

Inilah bagian yang sering membingungkan orang. Opsi `

--retry N

membuatcurl mencoba kembali mengatasi kesalahan sementara hingga N kali. Yang sering terlewatkan adalah bahwa ``--max-time

berlaku untuk *setiap upaya*, bukan untuk perintah secara keseluruhan, dan bahwacurl` menunggu di antara upaya-upaya tersebut dengan penundaan eksponensial yang dimulai dari satu detik dan berlipat ganda.

Jadi, ini:

curl -m 10 --retry 5 https://example.com

bisa memakan waktu lebih dari satu menit: lima upaya masing-masing hingga sepuluh detik, ditambah jeda backoff selama 1, 2, 4, 8, dan 16 detik. Jika Anda menulisnya dengan mengasumsikan batas waktu sepuluh detik, perkiraan Anda meleset enam kali lipat.

--retry-max-time

adalah solusinya. Opsi ini membatasi total waktu yang dihabiskan untuk mencoba ulang:

curl -m 10 --retry 5 --retry-max-time 40 https://example.com

Sekarang curl berhenti memulai upaya baru setelah 40 detik berlalu. Perhatikan redaksinya — curl tidak akan memulai upaya ulang baru setelah batas waktu tercapai, tetapi upaya yang sudah berjalan akan berlanjut hingga mencapai batas waktu tunggu eksponensialnya sendiri (--max-time

). Skenario terburuk yang sebenarnya adalah --retry-max-time

ditambah satu --max-time

--retry-delay

mengganti penundaan eksponensial dengan waktu tunggu tetap, yang membuat total waktu eksekusi dapat diprediksi:

curl -m 10 --retry 3 --retry-delay 2 --retry-max-time 40 https://example.com

Satu lagi opsi yang perlu diketahui: secara default, --retry

hanya terpicu pada sekumpulan kondisi sementara yang terbatas. --retry-all-errors

memperluas cakupannya secara signifikan — manualnya menjelaskannya sebagai upaya ulang "semua kesalahan sementara termasuk kode respons FTP 4xx dan 5xx". Fitur ini benar-benar berguna dalam skrip yang beroperasi di jaringan yang tidak stabil, namun juga sangat berbahaya jika digunakan pada permintaan POST yang tidak idempoten. Pertimbangkan dengan matang sebelum mengaktifkannya.

Batas Waktu Saat Menggunakan Proxy

Tambahkan -x

dan pola waktu akan berubah, karena kini terdapat dua koneksi, bukan satu: koneksi Anda ke proxy, dan koneksi proxy ke tujuan.

curl -x http://user:pass@proxy.example.com:9000 --connect-timeout 10 -m 45 https://example.com

Ada tiga hal yang berperilaku berbeda dibandingkan saat koneksi langsung.

**--connect-timeout

mengukur waktu yang dibutuhkan untuk mencapai proxy, bukan waktu yang dibutuhkan proxy untuk mencapai tujuan.** Untuk HTTPS, curl mengirimkan permintaan "CONNECT

" dan proxy yang membangun koneksi lanjutan; waktu yang dibutuhkan dihitung sebagai bagian dari "--max-time

", bukan "--connect-timeout

". Oleh karena itu, waktu tunggu koneksi yang singkat tidak akan melindungi Anda dari proxy yang menerima koneksi Anda dengan cepat namun membutuhkan waktu dua puluh detik untuk mencapai target.

Proxy residensial memang lebih lambat, secara wajar. Lalu lintas keluar melalui koneksi konsumen yang sebenarnya, sehingga penambahan beberapa ratus milidetik adalah hal yang normal, bukan kesalahan. Nilai batas waktu yang disesuaikan untuk koneksi langsung akan menghasilkan kegagalan yang tampak seperti proxy rusak, padahal sebenarnya hanya karena faktor fisik. Ukur melalui proxy dengan perintah ``-w`

` di atas dan tetapkan nilai berdasarkan pengukuran tersebut, bukan dari angka koneksi langsung Anda.

Kegagalan bersifat ambigu. Kode keluar 28 melalui proxy bisa berarti proxy lambat, target lambat, atau target sengaja menunda permintaan Anda. Membedakan ketiganya memerlukan pengujian komponen secara terpisah, yang merupakan topik yang cukup luas sehingga kami menulis panduan terpisah tentang pengujian proxy.

Pola praktis untuk permintaan melalui proxy: waktu tunggu yang cukup lama (--connect-timeout

) (10 detik), waktu tunggu antar-percobaan (--max-time

) yang ditetapkan berdasarkan perilaku yang terukur, bukan sekadar harapan, dan jangan gunakan waktu tunggu antar-percobaan (--retry-all-errors

), karena melalui proxy, kode 5xx sering kali berarti target menolak Anda, bukan sedang mengalami masalah sementara, dan mencoba lagi hanya akan memperburuk situasi.

Membaca Kode Keluar

Kode keluar curl memberi tahu Anda tahap mana yang gagal, yang merupakan informasi lebih banyak daripada yang biasanya dimanfaatkan oleh kebanyakan skrip.

Kode	Nama	Arti
6	`CURLE_COULDNT_RESOLVE_HOST`	DNS gagal — tidak ada batas waktu yang terlibat
7	`CURLE_COULDNT_CONNECT`	"Gagal melakukan connect() ke host atau proxy"
28	`CURLE_OPERATION_TIMEDOUT`	"Batas waktu yang ditentukan telah tercapai"
56	`CURLE_RECV_ERROR`	Gagal menerima data jaringan — koneksi terputus di tengah proses transfer

Deskripsi diambil dari referensi kesalahan libcurl.

Perbedaan antara kode 7 dan 28 sangat berguna. Kode 7 berarti koneksi ditolak secara aktif — ada respons yang mengatakan "tidak" dengan cepat. Kode 28 berarti tidak ada respons yang diterima tepat waktu. Yang pertama biasanya menandakan port yang salah atau layanan yang ditutup; yang kedua menandakan paket yang terputus, firewall yang menyaring secara diam-diam, atau host yang benar-benar kelebihan beban. Mencoba kembali adalah langkah yang wajar untuk kode 28 dan biasanya tidak berguna untuk kode 7.

Dalam skrip:

curl --connect-timeout 5 -m 30 -sS https://example.com > out.txt
case $? in
  0)  echo "ok" ;;
  6)  echo "dns failure" ;;
  7)  echo "connection refused" ;;
  28) echo "timed out" ;;
  *)  echo "other failure" ;;
esac

Perhatikan bahwa ketiga mekanisme batas waktu — --max-time, --connect-timeout, dan pasangan batas kecepatan — mengembalikan kode 28. Kode keluar tersebut memberitahu Anda bahwa batas telah tercapai, bukan batas mana yang tercapai. Jika Anda perlu mengetahuinya, gunakan -w "%{time_total}" dan bandingkan dengan nilai yang Anda konfigurasikan.

Kapan Tidak Perlu Menetapkan Batas Waktu

Meskipun bertentangan dengan saran umum, ada beberapa kasus di mana batas waktu bukanlah solusi yang tepat.

Unduhan interaktif. Jika Anda mengetik perintah curl di terminal untuk mengunduh berkas berukuran besar, Anda sendiri yang menentukan batas waktunya. Anda dapat melihat bilah kemajuan dan menekan Ctrl-C. Menambahkan -m di sini hanya akan menimbulkan ketidaknyamanan karena unduhan terhenti di 90%.

Aliran data yang berlangsung lama. Peristiwa yang dikirim server, pemantauan log secara real-time, respons bertahap yang dirancang untuk tetap terbuka — --max-time akan menghentikan aliran ini tepat pada saat yang salah. Gunakan --speed-limit dan --speed-time jika Anda memerlukan detektor kemacetan, atau jangan gunakan apa pun.

Apa pun yang sudah dibatasi oleh batasan eksternal. Jika curl berjalan di bawah timeout(1), unit systemd dengan RuntimeMaxSec, atau langkah CI dengan kuota sendiri, lapisan kedua hanya menambahkan angka kedua yang harus disinkronkan. Pilih lapisan yang menghasilkan pesan kesalahan yang ingin Anda baca dan atur di sana.

Sebagai solusi untuk target yang lambat. Batas waktu (timeout) membuat permintaan yang lambat gagal lebih cepat. Hal itu tidak membuatnya berhasil. Jika masalah sebenarnya adalah server membutuhkan 40 detik untuk merespons, opsi yang tersedia adalah caching, pagination, endpoint yang berbeda, atau berdiskusi dengan pihak yang mengelolanya — dan di sinilah kami akan mengulangi pernyataan penafian di bagian atas, karena ini adalah masalah paling umum yang ingin diselesaikan orang dengan membeli proxy dan salah satu dari sedikit hal yang sama sekali tidak dapat diselesaikan oleh proxy. Harga kami mulai dari $0,79/GB untuk lalu lintas residensial dan $0,14/GB untuk pusat data, diperbarui per September 2026, dan tidak satupun dari harga tersebut akan mempercepat server asal yang lambat.

Pertanyaan Lainnya

Berapa batas waktu default di curl?

Tidak ada batas waktu keseluruhan default — curl akan menunggu respons tanpa batas waktu setelah terhubung. Fase koneksi memang memiliki batas waktu default sebesar 300 detik. Inilah mengapa opsi -m penting dalam skrip: tanpa opsi ini, permintaan yang macet akan membuat skrip juga macet.

Apa perbedaan antara `--max-time` dan `--connect-timeout`?

--connect-timeout hanya mencakup resolusi DNS dan proses handshake TCP/TLS/QUIC, serta berhenti berlaku begitu koneksi terjalin. --max-time mencakup seluruh operasi dari awal hingga akhir, termasuk transfer respons. Gunakan keduanya — waktu tunggu koneksi yang singkat untuk kegagalan cepat pada host yang mati, dan waktu maksimum yang lebih lama sebagai batas atas keseluruhan.

Mengapa perintah curl saya memakan waktu lebih lama dari batas waktu yang saya tetapkan?

Hampir selalu karena upaya ulang. --max-time berlaku per upaya, dan --retry menambahkan upaya tambahan serta penundaan eksponensial di antara upaya-upaya tersebut. Tambahkan --retry-max-time untuk membatasi totalnya, dan ingat bahwa skenario terburuk adalah nilai tersebut ditambah satu lagi --max-time.

Bagaimana cara mengatur batas waktu curl dalam milidetik?

Gunakan nilai desimal: --connect-timeout 0.25 setara dengan 250 milidetik. Baik --max-time maupun --connect-timeout menerima nilai desimal dengan pemisah titik, yang didukung sejak curl 7.32.0. Presisi terbaik dicapai pada nilai di bawah beberapa detik; untuk nilai yang lebih besar, akurasi bagian pecahan akan menurun.

Kode keluar apa yang dikembalikan curl saat terjadi timeout?

28, CURLE_OPERATION_TIMEDOUT. Ketiga mekanisme timeout mengembalikan kode ini, sehingga kode tersebut menunjukkan bahwa batas telah tercapai, tetapi tidak menyebutkan mekanisme mana yang menyebabkan hal tersebut. Bandingkan dengan kode 7 (koneksi ditolak) dan 6 (kegagalan DNS), yang memiliki arti berbeda dan biasanya tidak boleh dicoba ulang.

Bagaimana cara membatasi waktu unduhan yang lambat tanpa menghentikan file berukuran besar?

Gunakan --speed-limit dan --speed-time alih-alih --max-time. Opsi ini hanya akan menghentikan unduhan jika throughput tetap di bawah ambang batas selama periode yang berkelanjutan, sehingga unduhan yang sah yang memakan waktu berjam-jam tidak terpengaruh, sementara unduhan yang macet akan segera dihentikan.

Apakah pengaturan batas waktu bekerja secara berbeda melalui proxy?

Ya. --connect-timeout hanya mengukur koneksi Anda ke proxy; koneksi lanjutan proxy ke tujuan dihitung melalui --max-time. Proxy residensial juga menambah latensi yang nyata, sehingga nilai yang disesuaikan untuk koneksi langsung akan menghasilkan kegagalan palsu. Lakukan pengukuran melalui proxy dan atur nilainya berdasarkan hasil tersebut.

Bisakah saya mengatur batas waktu hanya untuk resolusi DNS?

Tidak sebagai opsi terpisah — DNS sudah termasuk dalam --connect-timeout. Jika Anda memerlukan batasan khusus untuk DNS, lakukan resolusi secara terpisah dan kirimkan hasilnya dengan --resolve, yang sepenuhnya melewati proses pencarian DNS bawaan curl.

Kesimpulan

Ada dua opsi yang mencakup hampir semua kasus: --connect-timeout untuk kegagalan cepat saat host tidak dapat dijangkau, dan --max-time untuk batas maksimum secara keseluruhan. Atur keduanya, di setiap skrip, setiap saat. Pengaturan default yang menunggu selamanya merupakan pilihan yang wajar untuk alat interaktif, namun sangat buruk untuk otomatisasi.

Dua hal yang sering membuat orang kebingungan layak untuk diulang. --max-time berlaku per upaya, jadi setiap penggunaan --retry harus disertai dengan --retry-max-time; jika tidak, perintah sepuluh detik Anda akan berubah menjadi perintah satu menit. Dan batas waktu tetap bukanlah alat yang tepat untuk transfer dengan ukuran yang tidak dapat diprediksi — gunakan --speed-limit bersama --speed-time, dan Anda akan mendapatkan detektor kemacetan yang tidak mengganggu unduhan panjang yang sah.

Tentukan nilai-nilai berdasarkan pengukuran, bukan dari angka bulat yang sekadar terasa tepat. Satu kali menjalankan curl -w terhadap target Anda yang sebenarnya akan memberikan distribusi, dan batas waktu yang diturunkan dari distribusi tersebut akan gagal hanya ketika ada masalah yang benar-benar serius, bukan sekadar saat jaringan sedang mengalami gangguan biasa.

Cara Mengatur Batas Waktu dengan curl (+Contoh)