01 Jul 2025·6 menit membaca

Pola circuit breaker untuk API pihak ketiga di alur visual

Pelajari pola circuit breaker untuk API pihak ketiga dalam alur visual: tetapkan ambang, arahkan fallback, blokir retry yang berisik, dan kirim peringatan yang jelas.

Mengapa pemadaman API pihak ketiga merusak lebih dari satu fitur

Satu API pihak ketiga sering berada di tengah-tengah pekerjaan sehari-hari: menerima pembayaran, memeriksa alamat, menyinkronkan inventaris, mengirim pesan, memverifikasi identitas. Saat vendor tersebut bermasalah, jarang hanya satu tombol yang rusak. Seluruh alur yang bergantung pada respons itu bisa berhenti.

Itulah mengapa circuit breaker penting. Ini bukan teori — ini cara praktis agar operasi inti tetap berjalan meskipun integrasi bermasalah.

Lambat dan turun berdampak berbeda.

Saat API lambat, alur kerja Anda masih berusaha berhasil, tetapi setiap langkah menunggu. Pengguna melihat layar berputar, tim dukungan mendapat tiket “mandek”, dan pekerjaan latar belakang menumpuk. Lambat itu sulit karena bisa terlihat seperti sistem Anda sendiri yang gagal.

Saat API mati, Anda mendapatkan timeout atau error keras. Itu lebih jelas, tetapi sering lebih berbahaya karena alur kerja cenderung mencoba ulang. Ketika banyak permintaan mencoba ulang sekaligus, Anda menciptakan badai lalu lintas yang memperlambat pemulihan dan bisa menyeret sistem Anda sendiri.

Gejala umum muncul cepat: timeout, antrean yang terus tumbuh, pembaruan parsial, dan banyak pembersihan manual.

Kerusakan nyata adalah reaksi berantai. Jika penyedia tarif pengiriman lambat, penempatan pesanan melambat karena alur kerja menolak mengonfirmasi pesanan tanpa kuotasi. Jika pembayaran turun, dukungan mungkin terblokir untuk mengeluarkan pengembalian dana meskipun bagian lain bekerja.

Anda tidak bisa pura-pura gangguan tidak ada. Tujuannya adalah merancang alur dengan jalur fallback yang jelas, aturan pemblokiran sementara, dan alert sehingga bisnis bisa terus menerima pesanan, melayani pelanggan, dan mencatat pekerjaan sementara integrasi pulih.

Circuit breaker dengan kata-kata sederhana

Circuit breaker adalah sakelar pengaman untuk panggilan API. Ketika layanan pihak ketiga mulai gagal, breaker menghentikan alur Anda dari terus-menerus memukulnya. Alih-alih mengubah satu gangguan menjadi layar lambat, timeout, dan pekerjaan yang mandek, Anda mengendalikan radius dampak.

Circuit breaker memiliki tiga hasil sederhana:

Mengizinkan panggilan ketika vendor terlihat sehat.
Memblokir panggilan ketika kegagalan tinggi, dan langsung menjalankan jalur fallback.
Mencoba panggilan uji terbatas setelah jeda singkat untuk melihat apakah vendor pulih.

Jika Anda suka label, itu adalah “closed,” “open,” dan “half-open.” Nama bukan intinya. Kepastianlah yang penting. Ketika vendor bermasalah, alur Anda harus berperilaku sama setiap kali.

Ini tidak menyembunyikan error. Anda tetap mencatat kegagalan, menunjukkan status yang jelas kepada pengguna atau operasional, dan memberi peringatan kepada orang yang tepat. Anda memilih untuk gagal cepat, mengarahkan pekerjaan ke alternatif yang lebih aman, atau berhenti sebentar sebelum mencoba lagi.

Pilih panggilan API yang tak boleh menghentikan bisnis

Circuit breaker bekerja terbaik jika Anda selektif. Tidak setiap panggilan vendor pantas dilindungi khusus. Mulailah dengan langkah yang, jika diblokir, menghentikan uang, pesanan, atau akses pelanggan.

Metode praktis adalah mengikuti satu permintaan pengguna dari awal sampai akhir. Di mana timeout memaksa pengguna meninggalkan tugas, atau menciptakan kekacauan yang harus dibersihkan tim Anda?

Panggilan yang biasanya “tidak boleh memblokir pekerjaan inti” meliputi pembayaran, pengiriman dan pemenuhan, login/SSO/MFA, OTP dan pesan konfirmasi, serta pemeriksaan kepatuhan yang terkait dengan persetujuan.

Juga pisahkan langkah yang berhadapan dengan pengguna dari pekerjaan latar belakang. Jika seseorang menunggu di layar checkout, Anda perlu keputusan cepat: berhasil, fallback, atau berhenti dengan pesan yang jelas. Untuk pekerjaan latar belakang seperti sinkronisasi nomor pelacakan, retry yang lebih lambat boleh diterima selama tidak pernah memblokir alur utama.

Mulai kecil untuk menghindari perluasan lingkup. Lindungi 1–3 alur dulu, lalu perluas.

Tentukan apa arti “fallback yang aman” sebelum membangun apa pun. Fallback yang baik spesifik dan dapat diuji:

Pembayaran: simpan pesanan sebagai “payment pending” sehingga keranjang tidak hilang.
Pengiriman: gunakan tarif yang di-cache, tarif flat, atau konfirmasi pesanan dan tunda pembelian label.
Identitas: izinkan login dengan kata sandi saat SSO down, atau beralih ke verifikasi email.
Pesan: antre SMS untuk dikirim nanti dan sediakan jalur alternatif bila memungkinkan.

Di AppMaster’s Business Process Editor, ini biasanya menjadi cabang yang bersih: operasi inti berlanjut, sementara langkah yang bergantung vendor mengambil alternatif terkontrol.

Status, ambang, dan timer yang bisa Anda jelaskan

Circuit breaker adalah sakelar pengaman. Sebagian besar waktu ia membiarkan panggilan lewat. Ketika vendor mulai gagal, ia beralih untuk melindungi alur Anda dari waktu terbuang dan penumpukan error.

Tiga status

Closed adalah normal. Anda memanggil API dan melanjutkan.

Jika kegagalan melewati garis, breaker menjadi Open. Anda berhenti memanggil vendor untuk periode singkat dan langsung diarahkan ke fallback (nilai cache, pekerjaan yang di-queue, alur alternatif).

Setelah cooldown, breaker menjadi Half-open. Anda mengizinkan sejumlah kecil panggilan uji. Jika berhasil, kembali ke Closed. Jika gagal, kembali ke Open.

Apa yang diukur

Gunakan sinyal yang sesuai dengan cara vendor gagal:

Timeout
HTTP 5xx
Meningkatnya latensi (terlalu lambat untuk berguna)
Kesalahan koneksi/DNS
429 rate limit

Di alat alur visual, ini biasanya dipetakan ke pengecekan sederhana: kode status, waktu yang berlalu, dan output error tertentu.

Ambang awal dan dua timer kunci

Mulai dengan angka yang mudah dijelaskan, lalu sesuaikan berdasarkan lalu lintas nyata. Contoh:

Buka breaker jika 5–10 panggilan gagal dalam 30–60 detik.
Atau buka jika 20%–40% panggilan gagal dalam jendela bergulir.
Anggap latensi sebagai kegagalan ketika melebihi yang dapat ditoleransi proses Anda (sering 2–5 detik).

Lalu tetapkan dua timer:

Cooldown time (Open state): sering 30 detik sampai 5 menit.
Half-open test window: izinkan 1–5 panggilan uji, atau jendela waktu singkat seperti 10–30 detik.

Tujuannya sederhana: gagal cepat saat vendor tidak sehat, pulih otomatis saat kembali.

Langkah demi langkah: bangun circuit breaker di alur visual

Stop retry storms early

Use cooldowns and half-open probes so your system stays responsive.

Start Project

Pilihan desain terpenting adalah membuat keputusan “haruskah kita memanggil vendor sekarang?” di satu tempat, bukan tersebar di setiap alur.

1) Letakkan panggilan vendor di balik satu blok yang dapat digunakan ulang

Buat satu sub-proses (blok alur yang dapat digunakan ulang) yang dipakai setiap alur saat membutuhkan vendor itu. Di AppMaster, ini sesuai dengan Business Process yang dapat dipanggil dari endpoint atau automations. Jaga agar sempit: input masuk, permintaan vendor keluar, plus hasil sukses/gagal yang jelas.

2) Lacak kegagalan berdasarkan waktu, bukan hanya hitungan

Catat setiap hasil dengan cap waktu. Simpan hal seperti last success, last failure, failures within a window, current state, dan cooldown deadline.

Persistenkan field ini di tabel sehingga breaker bertahan restart dan konsisten di banyak instance. PostgreSQL lewat Data Designer cocok untuk ini.

3) Definisikan perubahan status yang akan diikuti setiap kali

Jaga aturannya sederhana. Contoh: jika 5 kegagalan terjadi dalam 2 menit, beralih ke Open. Saat Open, lewati panggilan vendor sampai cooldown lewat. Setelah cooldown, jadi Half-open dan izinkan satu percobaan terkendali. Jika berhasil, close breaker. Jika gagal, buka lagi.

4) Cabangkan alur: jalur vendor vs jalur fallback

Sebelum panggilan vendor, periksa state yang tersimpan:

Closed: panggil vendor, lalu perbarui sukses atau gagal.
Open: lewati panggilan dan jalankan fallback.
Half-open: izinkan percobaan terbatas, lalu putuskan apakah menutup atau membuka kembali.

Contoh: jika API label pengiriman turun, fallback bisa membuat pesanan dengan status “Label pending” dan antre pekerjaan retry, alih-alih memblokir checkout atau kerja gudang.

5) Buat shared di seluruh alur

Jika Anda punya banyak alur dan server, mereka harus membaca dan menulis state breaker yang sama. Kalau tidak, satu instance bisa terus memukul vendor sementara yang lain sudah memutuskan untuk berhenti.

Jalur fallback yang menjaga pekerjaan tetap berjalan

Circuit breaker hanya membantu jika Anda memutuskan apa yang terjadi saat panggilan diblokir. Fallback yang baik menjaga pengguna tetap bergerak, melindungi data Anda, dan membuat pembersihan nanti dapat diprediksi.

Pilih fallback yang cocok dengan tugas. Jika penyedia tarif pengiriman down, Anda mungkin tidak perlu harga tepat untuk menerima pesanan. Di alur visual, arahkan langkah API yang gagal ke cabang fallback yang tetap menghasilkan hasil yang berguna.

Dalam praktik, fallback biasanya seperti:

Gunakan nilai terakhir yang di-cache (dengan jendela kesegaran yang jelas).
Gunakan estimasi aman, diberi label secara jelas.
Rujuk ke tinjauan manual.
Antre pekerjaan untuk retry nanti (pekerjaan asinkron).

Pengalaman pengguna sama pentingnya dengan logika. Jangan tampilkan error kabur. Katakan apa yang terjadi dan apa yang bisa dilakukan pengguna selanjutnya: “Kami tidak dapat mengonfirmasi tarif saat ini. Anda bisa memesan dengan biaya pengiriman diperkirakan, atau menyimpannya untuk ditinjau.”

Juga rencanakan untuk gangguan singkat vs panjang. Gangguan singkat (menit) sering berarti “lanjutkan, retry di latar belakang.” Gangguan lebih lama (jam) mungkin memerlukan perilaku yang lebih ketat seperti tinjauan manual atau persetujuan.

Akhirnya, lacak setiap fallback sehingga rekonsiliasi mudah. Minimal, catat tipe fallback, detail permintaan asli, apa yang dikembalikan ke pengguna (dan apakah itu estimasi), serta status untuk tindak lanjut.

Aturan pemblokiran sementara dan retry yang lebih cerdas

Centralize API calls once

Wrap each vendor request in one reusable Business Process for consistent behavior.

Try AppMaster

Retry yang tidak terkendali mengubah masalah kecil vendor menjadi pemadaman nyata. Ketika banyak alur mencoba ulang bersamaan, mereka menimbulkan lonjakan (masalah “thundering herd”). Vendor melambat, antrean Anda tumbuh, dan batas laju terpakai.

Retry harus dapat diprediksi dan dibatasi, serta harus menghormati state breaker. Kebijakan praktis:

Batasi maksimal retry (sering 2–3).
Gunakan exponential backoff (misalnya, 2s, 8s, 30s).
Tambahkan jitter agar retry tidak sinkron.
Batasi total waktu retry (misalnya, 60–90 detik).
Jika breaker Open, jangan retry. Langsung ke fallback.

Pemblokiran sementara terkait tapi berbeda. Ini untuk kasus di mana respons memberi tahu Anda “ini tidak akan berhasil sekarang.” Aturan umum:

429 rate limit: blokir selama periode Retry-After (atau jendela aman tetap).
401/403 auth failure: blokir sampai kredensial diperbarui, lalu uji sekali.
5xx konsisten: blokir sebentar, lalu izinkan uji kecil.

Selama blok, putuskan apa yang terjadi pada pekerjaan yang sudah berjalan: antrekan, alihkan, atau degradasi dengan anggun (misalnya, terima pesanan tapi tunda “kirim SMS”).

Alerting yang memberi tahu apa yang harus dilakukan

Protect checkout from vendor outages

Add fast failover paths for payments and shipping without rewriting code.

Create Workflow

Circuit breaker hanya berguna jika orang cepat menerima notifikasi dan tahu apa yang harus dilakukan. Tujuannya bukan kebisingan. Ini satu pesan jelas saat perilaku berubah: panggilan diblokir, fallback aktif, atau breaker tetap open lebih lama dari yang diharapkan.

Pemicu default yang baik:

Alert saat breaker membuka.
Alert jika tetap open melewati batas waktu.
Alert pada lonjakan error yang tajam bahkan sebelum membuka.

Buat alert yang dapat ditindaklanjuti. Sertakan vendor dan endpoint, status saat ini dan kapan berubah, apa yang akan dirasakan pengguna, apa yang alur lakukan sekarang (memblokir, mencoba ulang, fallback), dan satu langkah yang disarankan.

Rute alert berdasarkan tingkat keparahan. API non-kritis bisa dikirim ke email. Pembayaran, login, atau pengiriman pesanan biasanya pantas mendapat paging. Di AppMaster ini cocok dipetakan ke cabang yang mengirim email, Telegram, atau SMS berdasarkan flag severity.

Lacak sekumpulan metrik kecil agar Anda dapat melihat apakah sedang pulih: panggilan yang diblokir dan penggunaan fallback per vendor seringkali cukup.

Contoh skenario: gangguan vendor tanpa menghentikan pesanan

Kegagalan umum: penyedia tarif pengiriman Anda turun tepat saat pelanggan checkout. Jika alur Anda mengharuskan tarif langsung saat pembuatan pesanan, satu gangguan bisa menghentikan seluruh pesanan.

Pada hari normal, pesanan dibuat, lalu alur meminta tarif langsung, dan pesanan disimpan dengan carrier dan harga yang dipilih.

Saat vendor mulai gagal, panggilan timeout atau mengembalikan 5xx. Setelah ambang tercapai (misalnya, 5 kegagalan dalam 2 menit), breaker terbuka.

Saat Open, alur berhenti memanggil penyedia pengiriman untuk jendela singkat (misalnya, 10 menit). Itu mencegah vendor yang gagal menyeret checkout untuk semua orang.

Alih-alih memblokir checkout, fallback bisa:

Menerapkan biaya flat (atau estimasi aman).
Membuat pesanan tetap.
Menandainya sebagai “Shipping rate pending” untuk perhitungan ulang nanti.
Menyimpan detail error vendor untuk tindak lanjut.

Di AppMaster, ini adalah cabang jelas di Business Process Editor, didukung oleh field Data Designer seperti shipping_rate_status dan shipping_rate_source.

Pemeriksaan cepat sebelum rilis

Turn logic into real source code

Generate Go, Vue3, and native mobile code from your visual workflows.

Generate App

Circuit breaker harus berperilaku sama saat beban tinggi seperti saat demo. Sebelum rilis, konfirmasi dasar-dasar:

Ambang dan cooldown terdokumentasi dan mudah diubah.
Open state langsung memblokir panggilan (tidak menunggu timeout vendor).
Perilaku fallback aman untuk uang dan janji pelanggan.
Half-open probing dibatasi ke beberapa panggilan uji.
Log memudahkan menjawab soal waktu dan dampak.

Habiskan waktu ekstra pada keamanan fallback. Fallback yang “menjaga pekerjaan berjalan” juga bisa menciptakan risiko keuangan. Jika provider pembayaran down, menandai pesanan sebagai dibayar berbahaya. Pendekatan yang lebih aman adalah “pending payment,” dengan pesan pelanggan yang jelas.

Uji pemulihan secara sengaja. Paksa kegagalan, pantau breaker terbuka, tunggu cooldown, dan konfirmasi Half-open hanya mengirim probe kecil. Jika berhasil, ia harus cepat menutup. Jika gagal, harus membuka kembali tanpa membanjiri vendor.

Log Anda harus menjawab, dalam waktu kurang dari satu menit: siapa yang terpengaruh, kapan mulai, langkah alur mana yang memicu breaker, dan fallback apa yang digunakan.

Langkah selanjutnya: terapkan pola di AppMaster

Pilih satu integrasi yang bisa merugikan operasi harian jika gagal (pembayaran, label pengiriman, SMS, sinkron CRM). Bangun breaker end-to-end untuk panggilan itu dulu. Setelah tim mempercayai perilakunya, ulangi template yang sama untuk vendor berikutnya.

Di AppMaster, model state breaker di PostgreSQL menggunakan Data Designer. Jaga sederhana: satu record per vendor (atau endpoint) dengan field seperti state, failure_count, last_failure_at, open_until, dan last_error singkat.

Lalu terapkan logika di Business Process Editor dengan cabang yang mudah dibaca. Kejelasan lebih penting daripada kecerdikan.

Urutan build praktis:

Periksa breaker state dan blokir panggilan saat open_until masih di masa depan.
Panggil API vendor dan tangkap output sukses serta error.
Saat sukses, reset counter dan close breaker.
Saat gagal, tingkatkan counter dan buka breaker saat ambang tercapai.
Arahkan alur yang berhadapan pengguna ke fallback (antre pekerjaan, gunakan data cache, atau izinkan proses manual).

Dokumentasikan keputusan fallback dengan bahasa sederhana supaya support dan ops tahu apa yang dilihat pengguna.

Saat breaker terbuka, beri tahu pemilik menggunakan modul messaging AppMaster (email, SMS, Telegram). Sertakan hal yang penting: vendor, endpoint, state, dan aksi pertama yang disarankan.

Jika Anda membangun alur ini di AppMaster, appmaster.io adalah tempat yang praktis untuk memulai karena Business Process visual yang sama bisa menjalankan endpoint, pekerjaan latar, dan alerting dengan satu state breaker yang dibagi.

FAQ

A circuit breaker stops repeated calls to a failing vendor and forces a fast, predictable outcome. Instead of waiting on timeouts and piling up retries, you either proceed normally, take a fallback path immediately, or allow a small test call after a cooldown.

It’s worth it when a vendor call can block money, orders, or customer access, or when failures create a queue that’s hard to clean up. Start with 1–3 high-impact workflows like checkout payments, shipping rates/labels, login/SSO, or OTP delivery.

“Slow” makes your system look broken because users wait, pages spin, and jobs back up even if the vendor eventually responds. “Down” is clearer but can be worse because many systems retry aggressively, causing a traffic storm that delays recovery and can overload your own infrastructure.

Closed means calls are allowed as normal. Open means calls are blocked for a short period and your workflow immediately uses a fallback. Half-open means you allow a small number of test calls after cooldown to check if the vendor is healthy again.

Use signals that match real failure: timeouts, HTTP 5xx, connection/DNS errors, rate limits (429), and latency that exceeds what your workflow can tolerate. Treat “too slow to be useful” as a failure so you fail fast instead of making users wait.

Start with simple rules you can explain, then tune from traffic. A common setup is opening after 5–10 failures in 30–60 seconds, or when 20%–40% of calls fail in a rolling window, with latency over 2–5 seconds counted as failure for user-facing steps.

A safe default is 30 seconds to 5 minutes for the Open cooldown, so you stop hammering the vendor while it’s unhealthy. In Half-open, allow only 1–5 test calls (or a brief window like 10–30 seconds) so you can recover quickly without flooding the vendor.

Pick a fallback that keeps work moving without lying about the outcome. Examples include saving an order as “payment pending,” using a cached or flat shipping rate with clear labeling, queueing messages for later, or routing the case to manual review.

Keep retries low (often 2–3), use exponential backoff, add jitter, and cap total retry time so you don’t clog queues. If the breaker is Open, don’t retry at all; go straight to fallback so you avoid creating a thundering herd.

Alert when the breaker opens, when it stays open too long, and when errors spike even before it opens. Each alert should say which vendor/endpoint is affected, what users will see, what fallback is active, when the state changed, and the next action your team should take.