Catatan penulis: Artikel ini membahas penyebab dan penanganan error 429, 401, dan 500 pada AI API berdasarkan kode error. Kita juga akan membahas error mana yang perlu dicoba ulang, mana yang perlu diperbaiki konfigurasinya, serta kapan exponential backoff, fallback multimodel, dan circuit breaker cocok digunakan.
Saat memanggil Model Bahasa Besar di lingkungan produksi, banyak developer pernah melihat rentetan error 429, 401, dan 500 muncul di grup peringatan pada dini hari. Respons yang umum adalah mencoba ulang semua permintaan yang gagal, tetapi langkah ini sering kali justru memperburuk keadaan. Artikel ini membahas cara menganalisis error 429, 401, dan 500 pada AI API serta merancang toleransi kesalahan berdasarkan kode error, agar kamu bisa mengganti “coba ulang secara membabi buta” dengan “penanganan sesuai jenis error”.
Ini bukan artikel pengantar tentang kode status HTTP, melainkan panduan praktis untuk operasional sistem produksi. Kita akan membahas penyebab umum setiap jenis error, apakah permintaan bisa dicoba ulang, cara menulis logika penanganan di lapisan aplikasi, serta pembagian tanggung jawab toleransi kesalahan antara lapisan gateway dan aplikasi.
Manfaat utama: Setelah membaca artikel ini, kamu bisa menentukan dalam hitungan menit apakah sebuah error perlu dicoba ulang, ditangani dengan fallback, atau segera diperbaiki konfigurasinya. Kamu juga akan memahami kapan exponential backoff, fallback multimodel, dan circuit breaker cocok digunakan.
Poin Penting tentang Error 429, 401, dan 500 pada AI API
Saat menangani error AI API, langkah pertama adalah mengelompokkannya, baru kemudian mempertimbangkan percobaan ulang. Setiap kode error menunjukkan jenis masalah yang berbeda: ada yang bisa pulih setelah beberapa saat, ada juga yang akan terus gagal meski dicoba berulang kali. Tabel berikut memberikan gambaran umum tiap kategori error.
| Kategori error | Kode status umum | Penyebab utama | Bisa dicoba ulang? | Penanganan utama |
|---|---|---|---|---|
| Batas laju | 429 | Permintaan terlalu cepat atau kuota habis | Bergantung pada penyebabnya | Baca Retry-After, gunakan penundaan eksponensial, dan bedakan batas laju dari kuota yang habis |
| Autentikasi | 401、403 | Kunci tidak valid atau izin tidak memadai | Tidak | Segera hentikan percobaan ulang, kirim peringatan, dan perbaiki konfigurasi |
| Server | 500、502、503、504 | Layanan upstream bermasalah atau kelebihan beban | Bisa, dengan batas | Coba ulang dengan penundaan dalam jumlah terbatas; jika terus gagal, gunakan fallback atau circuit breaker |
| Permintaan | 400、404、413、422 | Parameter, nama model, atau panjang permintaan tidak tepat | Tidak | Catat body permintaan, perbaiki parameter, lalu kirim ulang |
Intinya, keputusan untuk mencoba ulang bergantung pada apakah error bersifat sementara atau pasti. Percobaan ulang berguna untuk error sementara, seperti pembatasan laju atau gangguan upstream. Untuk error yang pasti, seperti kunci atau parameter yang salah, percobaan ulang hanya membuang kuota, memperlambat respons, dan bahkan bisa memicu pembatasan laju yang lebih ketat.
Tabel Keputusan untuk Mendiagnosis Kode Kesalahan API AI
Saat melakukan diagnosis, kode status saja tidak cukup. Perhatikan juga kolom jenis kesalahan dalam isi respons dan header respons. Tabel berikut dapat langsung digunakan untuk merancang logika di tingkat aplikasi.
| Sinyal yang diamati | Kemungkinan penyebab | Tindakan yang disarankan | Dihitung dalam statistik circuit breaker? |
|---|---|---|---|
429 dengan header Retry-After |
Batas laju permintaan | Tunggu sesuai waktu yang tertera di header, lalu coba lagi | Tidak |
| 429 dengan isi kesalahan yang menunjukkan kuota atau saldo tidak cukup | Kuota akun habis | Jangan coba lagi; kirim peringatan untuk mengisi saldo atau beralih akun | Tidak |
| 401 | Kunci salah, kedaluwarsa, atau formatnya tidak sesuai | Jangan coba lagi; periksa kunci dan variabel lingkungan | Tidak |
| 403 | Kunci tidak punya akses ke model atau wilayah tersebut | Jangan coba lagi; periksa izin dan status akses model | Tidak |
| 500 / 502 | Kesalahan internal pada layanan upstream atau kegagalan penerusan gateway | Coba lagi 2-3 kali dengan jeda bertahap | Ya |
| 503 | Layanan kelebihan beban atau sedang dalam pemeliharaan | Coba lagi dengan jeda bertahap; jika gagal, gunakan layanan alternatif | Ya |
| 504 atau timeout klien | Proses generasi terlalu lama atau respons upstream lambat | Tentukan apakah perlu mencoba lagi berdasarkan idempotensi; pertimbangkan menambah batas timeout | Ya |
Hal yang paling mudah terlewat dalam tabel ini adalah dua makna dari kode 429. Beberapa penyedia juga mengembalikan 429 saat kuota habis, tetapi kolom jenis dalam isi kesalahannya berbeda dari pembatasan laju biasa. Jika aplikasi hanya memeriksa kode status, permintaan dengan “saldo tidak cukup” akan terus dicoba lagi dengan jeda bertahap. Log akan penuh dengan kode 429, tetapi masalahnya tidak akan pernah pulih.
Penjelasan utama error 429 akibat pembatasan laju
Penyebab utama error 429 adalah jumlah permintaan atau token yang melebihi batas dalam periode tertentu. Pembatasan laju API Model Bahasa Besar biasanya mencakup beberapa dimensi: jumlah permintaan per menit, jumlah token per menit, dan terkadang jumlah permintaan bersamaan. Jadi, meskipun jumlah permintaannya sedikit, konteks yang terlalu panjang dalam satu permintaan juga bisa memicu 429.
Ada tiga prinsip untuk menangani 429 di lapisan aplikasi. Pertama, utamakan header Retry-After atau header waktu reset serupa; jangan menebak waktu tunggu sendiri. Kedua, jika tidak ada petunjuk di header, gunakan exponential backoff dengan jitter acak agar banyak klien tidak mencoba lagi secara bersamaan dan kembali memenuhi batas. Ketiga, kendalikan aliran permintaan dari sumbernya menggunakan token bucket atau antrean untuk membatasi permintaan bersamaan. Cara ini lebih efektif daripada mencoba ulang setelah error terjadi.
Penjelasan utama error autentikasi 401
Error 401 adalah error yang paling tidak perlu dicoba ulang. Penyebabnya hampir selalu masalah konfigurasi, seperti spasi atau baris baru yang ikut tersalin dalam kunci, variabel lingkungan yang tidak dimasukkan dengan benar ke container, kunci lingkungan pengujian yang terbawa ke produksi, kunci yang sudah dirotasi atau dicabut, atau format header autentikasi yang salah.
Pada antarmuka yang kompatibel dengan OpenAI, penyebab lain yang sering terjadi adalah base_url dan kunci tidak cocok, misalnya menggunakan kunci platform A untuk mengirim permintaan ke alamat platform B. Karena itu, saat 401 terjadi, lapisan aplikasi harus segera berhenti mencoba ulang, memicu peringatan berprioritas tinggi, serta mencatat beberapa karakter awal kunci dan alamat permintaan dalam log agar masalah cepat ditemukan. Namun, jangan mencatat kunci secara lengkap.
Penjelasan Penting tentang Kesalahan Server 500
Kesalahan seri 500 menunjukkan adanya masalah pada server atau jalur koneksi. Penyebabnya bisa berupa gangguan internal atau beban berlebih pada layanan model upstream, maupun kegagalan penerusan oleh gateway perantara. Kesalahan ini biasanya bersifat sementara, sehingga permintaan dapat dicoba ulang beberapa kali dengan batas yang jelas. Namun, jika terus terjadi, kemungkinan layanan upstream sedang tidak sehat. Melanjutkan percobaan ulang hanya akan membuat permintaan mengantre dan memenuhi thread; sebaiknya beralih ke penurunan layanan atau pemutusan sirkuit.
Perhatikan juga kesalahan 504 dan timeout di sisi klien. Model Bahasa Besar memang membutuhkan waktu untuk menghasilkan teks panjang. Jika batas timeout terlalu singkat, permintaan yang berjalan normal tetapi lambat bisa dianggap gagal lalu dicoba ulang. Hal ini dapat menimbulkan biaya ganda. Jika output streaming terputus, frontend juga bisa menerima konten yang terpotong.
Panduan cepat retry, fallback, dan circuit breaker untuk API AI
Setelah mengelompokkan jenis kesalahan, langkah berikutnya adalah menerapkan logika penanganannya dalam kode. Sesuai ketentuan tambahan, bagian ini tidak menyertakan blok kode, melainkan menjelaskan poin implementasi setiap mekanisme melalui daftar parameter dan langkah-langkah yang bisa diterapkan dalam bahasa pemrograman apa pun.
Poin implementasi retry dengan exponential backoff
Exponential backoff bekerja dengan menambah waktu tunggu secara berlipat pada setiap retry, lalu menambahkan jitter acak. Logikanya bisa disusun seperti berikut:
- Tentukan kumpulan kesalahan yang boleh dicoba ulang, misalnya
429(selain karena kuota habis),500,502,503,504, dan timeout jaringan. - Setelah setiap kegagalan, periksa
Retry-Afterdi header respons. Jika ada, ikuti waktu tunggu yang ditentukan; jika tidak, hitung waktu tunggu dengan rumus backoff. - Rumus waktu tunggu biasanya berupa “interval dasar × 2 pangkat jumlah retry”, ditambah nilai jitter acak. Tetapkan juga batas maksimum untuk setiap waktu tunggu.
- Tetapkan jumlah retry maksimum dan batas total waktu. Jika salah satunya terlampaui, segera hentikan percobaan dan serahkan kesalahan ke logika fallback.
- Catat log setiap retry, termasuk kode kesalahan, jumlah retry, durasi tunggu, dan nama model agar mudah dianalisis kemudian.
Jika menggunakan SDK resmi, banyak SDK sudah menyediakan parameter seperti max_retries dan timeout. Perhatikan agar tidak menambahkan lapisan retry yang sama di luar SDK. Jika tidak, jumlah retry bisa berlipat dan memperbesar volume permintaan saat terjadi gangguan.
Tabel berikut memberikan contoh parameter awal yang umum digunakan berdasarkan pengalaman. Sesuaikan nilainya dengan kebutuhan latensi bisnis dan batas layanan penyedia.
| Parameter | Arti | Nilai awal yang umum | Dasar penyesuaian |
|---|---|---|---|
max_retries |
Jumlah retry maksimum | 2–5 kali | Gunakan nilai kecil untuk percakapan real-time; batch offline bisa menggunakan nilai lebih besar |
| Interval dasar | Waktu tunggu sebelum retry pertama | Sekitar 1 detik | Bisa diperbesar untuk layanan dengan pembatasan laju yang ketat |
| Batas waktu tunggu per percobaan | Batas atas waktu backoff | Puluhan detik | Hindari waktu tunggu yang terlalu lama hingga menghambat permintaan |
| Jitter acak | Menyebarkan waktu retry | Nilai acak yang merupakan sebagian dari waktu tunggu | Semakin banyak klien yang berjalan bersamaan, semakin dibutuhkan |
| Batas total waktu | Durasi maksimum satu pemanggilan | Sesuai SLA bisnis | Langsung lakukan fallback setelah batas waktu terlampaui |
🚀 Mulai cepat: Untuk menyimulasikan perilaku retry pada berbagai kode kesalahan selama pengujian, kamu bisa menggunakan APIYI apiyi.com untuk mengakses beberapa model melalui antarmuka terpadu yang kompatibel dengan OpenAI. Dengan begitu, kamu bisa mengamati respons dan kesalahan dari berbagai model menggunakan logika retry yang sama, tanpa perlu membuat penyesuaian terpisah untuk setiap penyedia layanan.
Cara Merancang Fallback Multimodel
Percobaan ulang menangani situasi ketika “model yang sama sementara tidak tersedia”, sedangkan fallback menangani situasi ketika “model tersebut tidak dapat pulih dalam waktu singkat”. Fallback multimodel berarti menyiapkan jalur cadangan sejak awal: setelah model utama gagal berturut-turut, sistem beralih ke model cadangan secara berurutan agar layanan tetap bisa merespons. Konsekuensinya, kualitas mungkin sedikit menurun atau biaya meningkat.
Saat merancang rantai fallback, pertimbangkan apakah kemampuan setiap model setara. Jika model utama mengandalkan pemanggilan fungsi, output terstruktur, atau konteks panjang, model cadangan juga harus mendukung fitur tersebut. Jika tidak, fallback bisa menimbulkan kesalahan 400 baru atau kegagalan saat mengurai format output. Tabel berikut memberikan contoh rancangan rantai fallback berdasarkan skenario.
| Skenario bisnis | Peran model utama | Cadangan pertama | Fallback kedua | Platform yang tersedia |
|---|---|---|---|---|
| Percakapan layanan pelanggan online | Model serbaguna berkualitas tinggi | Model setara dari penyedia lain | Model ringan dan cepat + jawaban sederhana | APIYI apiyi.com, API resmi masing-masing penyedia |
| Pembuatan dan peninjauan kode | Model unggulan dengan kemampuan pemrograman yang kuat | Model unggulan dari penyedia lain | Kembalikan pesan “coba lagi nanti” | APIYI apiyi.com, API resmi masing-masing penyedia |
| Pemrosesan konten secara batch | Model dengan rasio harga dan performa yang baik | Model lain dengan harga setara | Masukkan ke antrean untuk diproses nanti | APIYI apiyi.com, API resmi masing-masing penyedia |
| Ekstraksi informasi terstruktur | Model yang mendukung output JSON | Model lain yang juga mendukung output terstruktur | Gunakan mesin aturan sebagai fallback | APIYI apiyi.com, API resmi masing-masing penyedia |
Ada beberapa hal yang perlu diperhatikan saat melakukan fallback:
- Penyesuaian petunjuk: Setiap model memiliki tingkat sensitivitas yang berbeda terhadap petunjuk sistem. Sebaiknya siapkan versi petunjuk tersendiri yang sudah divalidasi untuk model cadangan.
- Panjang konteks: Sebelum beralih, periksa apakah panjang pesan melebihi jendela konteks model cadangan. Jika perlu, pangkas riwayat terlebih dahulu.
- Penandaan hasil: Tandai di log dan sistem pemantauan bahwa “respons ini berasal dari model fallback” agar dampaknya terhadap kualitas mudah dievaluasi.
- Jangan lakukan fallback untuk kesalahan autentikasi: Kesalahan 401 menunjukkan adanya masalah konfigurasi. Beralih model hanya akan menutupi masalah, jadi langsung kirimkan peringatan.
Cara kerja dan batas penggunaan pemutus sirkuit
Pemutus sirkuit (circuit breaker) mencegah satu dependensi yang terus mengalami gangguan melumpuhkan seluruh sistem. Mekanisme ini biasanya memiliki tiga status: saat tertutup, permintaan diteruskan seperti biasa sambil menghitung tingkat kegagalan. Jika tingkat atau jumlah kegagalan berturut-turut melewati ambang batas, status berubah menjadi terbuka. Pada status ini, permintaan langsung ditolak atau dialihkan ke mekanisme fallback, tanpa lagi mengakses layanan hulu yang bermasalah. Setelah masa tunggu, status berubah menjadi setengah terbuka dan sejumlah kecil permintaan percobaan diteruskan. Jika berhasil, status kembali tertutup; jika gagal, status kembali terbuka.
Kunci pemutus sirkuit adalah hanya menghitung kesalahan yang mencerminkan kondisi layanan hulu. Kesalahan 5xx dan waktu habis (timeout) perlu dihitung sebagai kegagalan, sedangkan kesalahan klien seperti 401 dan 400 tidak. Jika tidak, satu kesalahan konfigurasi bisa membuka pemutus sirkuit dan membuat semua permintaan normal ditolak. Respons 429 akibat kuota tidak mencukupi juga tidak perlu dihitung karena mencerminkan status akun, bukan kondisi layanan.
Pemutus sirkuit juga tidak selalu perlu digunakan. Pada alat internal dengan volume pemanggilan sangat rendah, sampel untuk menghitung tingkat kegagalan terlalu sedikit sehingga pemutus sirkuit mudah salah mengambil keputusan. Dalam kasus ini, percobaan ulang sederhana dan fallback sudah cukup. Pemutus sirkuit lebih cocok untuk layanan produksi dengan tingkat konkurensi tinggi: mekanisme ini dapat segera membatasi dampak saat terjadi gangguan luas di layanan hulu, sehingga kumpulan thread dan koneksi tidak dipenuhi oleh permintaan yang lambat.
Pembagian Tugas Toleransi Kesalahan di Lapisan Gateway dan Aplikasi
Semakin banyak tim menggunakan gateway API atau platform agregasi untuk memanggil Model Bahasa Besar. Pertanyaan yang sering muncul: jika gateway sudah memiliki penurunan layanan otomatis, apakah lapisan aplikasi masih perlu melakukan percobaan ulang dan menerapkan circuit breaker? Jawabannya ya, tetapi tugasnya berbeda. Gateway lebih cocok menangani masalah di tingkat kanal upstream, sedangkan lapisan aplikasi lebih memahami makna dan kebutuhan bisnis.
| Tanggung jawab toleransi kesalahan | Lebih cocok di lapisan gateway | Lebih cocok di lapisan aplikasi |
|---|---|---|
| Pengalihan saat kanal gagal | Beralih antar kanal untuk model yang sama dan melakukan penyeimbangan beban | Tidak perlu mengimplementasikannya lagi |
| Penurunan layanan lintas model | Menyediakan kemampuan perutean model | Menentukan apakah bisnis menerima penurunan kualitas dan apakah petunjuk perlu diubah |
| Percobaan ulang | Percobaan ulang cepat di tingkat kanal | Batas percobaan ulang di tingkat bisnis dan penyesuaian dengan batas waktu pengguna |
| Circuit breaker | Pemeriksaan kesehatan kanal upstream | Circuit breaker dan solusi cadangan saat seluruh gateway tidak dapat diakses |
| Kesalahan autentikasi dan kuota | Mengembalikan jenis kesalahan yang jelas | Memberikan peringatan, menghentikan percobaan ulang, dan meminta penanganan manual |
| Pemantauan | Tingkat keberhasilan dan latensi di tingkat kanal | Tingkat keberhasilan bisnis, proporsi penurunan layanan, dan dampak terhadap pengguna |
Sebagai contoh, APIYI menyebutkan kemampuan stabilitas seperti penurunan layanan otomatis, penyeimbangan beban, dan pemantauan waktu nyata dalam penjelasan layanannya. Kemampuan ini cocok untuk menangani pengalihan saat kanal gagal, sehingga lapisan aplikasi bisa berfokus pada solusi cadangan untuk kebutuhan bisnis. Namun, kondisi pemicu penurunan layanan di gateway, serta kesesuaian kode dan format isi kesalahan yang dikembalikan dengan API resmi, perlu dipastikan melalui dokumentasi platform dan pengujian langsung. Klaim “konkurensi tanpa batas” dalam penjelasan layanan juga tidak berarti kesalahan 429 tidak akan pernah muncul, karena batasan pada model upstream tetap berlaku. Langkah yang aman adalah selalu mempertahankan logika penanganan 429 dan 5xx di lapisan aplikasi, serta menyiapkan solusi cadangan saat gateway secara keseluruhan tidak dapat diakses.
🎯 Saran teknis: Setelah menghubungkan gateway, coba picu beberapa jenis kesalahan di lingkungan pengujian, misalnya dengan menggunakan kunci yang salah, meminta nama model yang tidak ada, atau mengirim konteks yang terlalu panjang. Catat kode status dan field isi kesalahan yang benar-benar dikembalikan oleh APIYI apiyi.com, lalu sesuaikan aturan klasifikasi kesalahan di lapisan aplikasi berdasarkan hasil tersebut, alih-alih langsung menyalin format kesalahan dari dokumentasi resmi.
Pertanyaan yang Sering Diajukan (FAQ)
Q1: Apa perbedaan mendasar antara error 429 dan 500 pada API AI?
Error 429 berarti permintaan Anda melampaui batas, baik karena laju pemanggilan maupun kuota akun. Error 500 berarti terjadi masalah pada server penyedia. Untuk 429, kurangi laju permintaan dan patuhi waktu tunggu; untuk 500, coba ulang dengan jumlah terbatas, lalu lakukan fallback jika terus gagal. Keduanya mungkin pulih setelah beberapa saat, tetapi fokus penanganannya berbeda.
Q2: Mengapa error 401 tidak boleh dicoba ulang secara otomatis?
Error 401 bersifat deterministik: jika kunci salah, hasilnya akan tetap sama meskipun dicoba ulang sepuluh ribu kali. Percobaan ulang otomatis tidak hanya membuang sumber daya, tetapi juga menutupi masalah dan menunda peringatan. Sebaiknya segera hentikan proses, lalu periksa isi kunci API, injeksi variabel lingkungan, dan apakah alamat permintaan sudah sesuai.
Q3: Apa penyebab error 429 tidak kunjung pulih meski terus dicoba ulang?
Penyebab paling umum adalah kuota atau saldo habis. Sebagian penyedia juga mengembalikan error 429 dalam kondisi ini, tetapi field jenis pada isi error berbeda dari pembatasan laju biasa. Kemungkinan lain, percobaan ulang tidak menggunakan jitter acak sehingga banyak permintaan dikirim ulang secara bersamaan dan terus menghabiskan batas yang tersedia. Periksa isi error terlebih dahulu, lalu periksa distribusi waktu percobaan ulang.
Q4: Apakah fallback ke model lain memengaruhi kualitas output?
Bisa. Fallback pada dasarnya menukar kualitas dengan ketersediaan, jadi tentukan di tingkat bisnis skenario mana yang bisa menerima penurunan kualitas. Siapkan petunjuk yang telah diuji secara terpisah untuk model cadangan, dan pantau proporsi penggunaan fallback. Jika proporsinya terus tinggi, periksa kuota dan stabilitas model utama.
Q5: Bagaimana cara menguji alur fallback antar-model dengan biaya rendah?
Anda bisa menggunakan platform yang menyediakan antarmuka terpadu untuk berbagai model. Misalnya, melalui APIYI apiyi.com, Anda dapat beralih antara model dari berbagai penyedia menggunakan metode pemanggilan yang kompatibel dengan OpenAI. Cukup ubah nama model untuk membandingkan output dan perilaku error model utama dan cadangan dengan petunjuk yang sama. Cara ini cocok untuk menguji fallback sebelum peluncuran.
Q6: Jika menggunakan gateway dengan fallback otomatis, apakah lapisan aplikasi masih memerlukan circuit breaker?
Ya. Fallback di gateway menangani masalah pada saluran penyedia, tetapi gateway itu sendiri juga bisa mengalami gangguan jaringan atau tidak tersedia sama sekali. Circuit breaker dan mekanisme cadangan di lapisan aplikasi disiapkan untuk kondisi tersebut. Saat menggunakan gateway seperti APIYI, Anda bisa mengatur circuit breaker di lapisan aplikasi untuk memantau “gateway secara keseluruhan”, bukan setiap saluran model, sehingga tanggung jawab kedua lapisan tidak tumpang tindih.
Q7: Apa saja efek samping yang perlu diketahui dari percobaan ulang, fallback, dan circuit breaker?
Percobaan ulang dapat menyebabkan penagihan ganda dan, dalam operasi non-idempoten seperti operasi tulis yang melibatkan pemanggilan tool, dapat membuat tindakan dijalankan berulang kali. Fallback dapat menyebabkan perubahan kualitas dan perbedaan format output. Parameter circuit breaker yang terlalu sensitif dapat menolak permintaan yang sebenarnya normal. Karena itu, ketiganya perlu terus disesuaikan berdasarkan metrik pemantauan, bukan dikonfigurasi sekali lalu dibiarkan.
Poin Penting Penanganan Error AI API
- Klasifikasikan sebelum menangani: Perbaiki error deterministik segera; hanya error sementara yang masuk ke proses percobaan ulang.
- Periksa isi respons error 429: Bedakan pembatasan laju dari kuota habis. Percobaan ulang tidak berguna jika kuota habis.
- Jangan pernah mencoba ulang error 401: Segera kirim peringatan, lalu periksa kesesuaian kunci API, variabel lingkungan, dan alamat endpoint.
- Batasi percobaan ulang: Gunakan exponential backoff dengan jitter acak, serta tetapkan batas jumlah percobaan dan total durasi.
- Samakan kemampuan saat fallback: Model cadangan harus mendukung fitur yang sama dan memiliki petunjuk tersendiri.
- Circuit breaker hanya menghitung error server: Masukkan 5xx dan timeout ke tingkat kegagalan, tetapi jangan hitung error klien.
- Bagi tugas gateway dan aplikasi: Gunakan APIYI apiyi.com untuk menangani toleransi kegagalan di tingkat kanal, sementara lapisan aplikasi menangani fallback bisnis.
Kesimpulan
Saat AI API mengembalikan error 429, 401, atau 500, hal terpenting adalah meninggalkan kebiasaan “mencoba ulang semua error” dan menanganinya sesuai sifatnya:
- Error pembatasan laju: Patuhi
Retry-After, coba ulang dengan exponential backoff dan jitter, serta kendalikan konkurensi dan penggunaan token dari sumbernya. - Error autentikasi dan permintaan: Segera hentikan proses, kirim peringatan, dan perbaiki konfigurasi. Jangan pernah mencoba ulang secara otomatis atau menggunakan fallback untuk menutupi masalah.
- Error server: Coba ulang dalam jumlah terbatas. Jika kegagalan berlanjut, beralih ke model cadangan; pada konkurensi tinggi, gunakan circuit breaker untuk segera membatasi dampaknya.
- Pemisahan gateway dan aplikasi: Gateway menangani pergantian kanal dan beban, sedangkan lapisan aplikasi mengelola semantik bisnis, batas percobaan ulang, dan fallback terakhir.
Sebaiknya mulai dengan menyusun tabel keputusan dalam artikel ini menjadi standar penanganan error internal tim. Setelah itu, lakukan simulasi gangguan untuk memastikan setiap jenis error mengikuti alur yang diharapkan.
Jika sedang merancang alur fallback multimodel, kamu bisa menggunakan APIYI apiyi.com untuk membandingkan performa dan perilaku error beberapa model melalui satu antarmuka. Uji strategi toleransi kegagalan di lingkungan pengujian sebelum menerapkannya ke produksi.
📚 Referensi
- Ofox.ai Blog – Artikel tentang Penanganan Error AI API: Membahas cara menangani pembatasan laju 429, autentikasi 401, dan kesalahan server 500, serta exponential backoff, fallback multimodel, dan circuit breaker
- Tautan:
ofox.ai/blog/page/41/ -
Keterangan: Referensi untuk topik artikel ini, cocok sebagai bacaan pendamping dalam bahasa Inggris
-
Ofox.ai Blog – Artikel terkait LLM API Gateway: Membahas pemilihan gateway LLM dan latar belakang kegagalan pada berbagai penyedia layanan
- Tautan:
ofox.ai/blog/page/40/ -
Keterangan: Untuk memahami peran toleransi kesalahan pada lapisan gateway dalam arsitektur multimodel
-
Pusat Dokumentasi APIYI: Panduan integrasi dan dokumentasi penggunaan platform
- Tautan:
docs.apiyi.com - Keterangan: Untuk detail seperti format kode error dan perilaku fallback, rujuk dokumentasi platform dan hasil pengujian aktual
Penulis: Tim Teknis APIYI
Diskusi teknis: Hubungi kami melalui halaman utama situs APIYI untuk berdiskusi tentang praktik menjaga stabilitas AI API. Panduan integrasi lainnya tersedia di pusat dokumentasi docs.apiyi.com
