Catatan penulis: Panduan ini membahas cara memilah error API model berdasarkan kode error: kapan perlu mencoba ulang, kapan beralih ke model cadangan, dan kapan harus berhenti untuk memperbaiki konfigurasi. Di dalamnya ada tabel triase kode error, daftar verifikasi model cadangan, dan daftar pemeriksaan sebelum peluncuran.
Saat API model mengembalikan error, kenali dulu jenisnya sebelum menentukan langkah penanganan. Sebagian besar error 4xx disebabkan oleh masalah pada permintaan atau konfigurasi, sehingga mencoba ulang tidak akan memperbaikinya. Error 5xx, 529, dan timeout layak ditangani dengan percobaan ulang terbatas; jika masih gagal, beralihlah ke model cadangan. Jangan otomatis mencoba ulang permintaan tanpa jaminan idempotensi. Mencoba ulang bukanlah tindakan bawaan, dan beralih model juga tidak menyelesaikan semua masalah. Banyak insiden produksi bukan terjadi karena model bermasalah, melainkan karena logika penanganan error memperbesar gangguan kecil hingga menyebabkan penagihan ganda, penulisan data berulang, dan pembatasan laju di seluruh alur.
Artikel ini bukan terjemahan kamus kode error. Artikel ini ditujukan bagi developer yang sudah mengintegrasikan API model ke lingkungan produksi atau semiproduksi, dengan fokus pada cara mencegah situasi memburuk saat terjadi error. Setelah membacanya, kamu akan mendapatkan tabel triase kode error, strategi percobaan ulang dan fallback, daftar verifikasi kemampuan model cadangan, serta daftar pemeriksaan sebelum peluncuran yang bisa langsung digunakan. Intinya bisa diringkas dalam satu pedoman: perbaiki dulu 4xx, pertimbangkan percobaan ulang untuk 5xx, dan hentikan dulu permintaan yang tidak idempoten.
Triase 5 jenis kesalahan API model: klasifikasikan sebelum mencoba ulang atau beralih
Intinya, kesalahan API model bisa dibagi menjadi lima jenis, masing-masing dengan arah penanganan yang relatif tetap. Klasifikasikan kode kesalahan terlebih dahulu agar logika mencoba ulang dan beralih tetap jelas.
| Jenis kesalahan | Kode status umum | Sumber masalah | Tindakan awal |
|---|---|---|---|
| Kesalahan permintaan | 400, 404, 409, 422 |
Body permintaan, parameter, ID model, endpoint | Jangan coba ulang; perbaiki permintaan |
| Kesalahan autentikasi atau otorisasi | 401, 403 |
Kunci API, header permintaan, izin, wilayah, atau kebijakan | Jangan coba ulang; periksa kunci API dan izin |
| Kuota atau pembatasan laju | 402, 429 |
Saldo, konkurensi, laju, kuota model | 402: hentikan; 429: periksa body kesalahan, lalu terapkan backoff atau beralih |
| Gangguan upstream | 500, 502, 503, 529 |
Gateway, layanan upstream, beban berlebih | Coba ulang dalam jumlah terbatas; jika gagal, beralih |
| Timeout atau aliran terputus | 408, 504, timeout jaringan, aliran terputus |
Koneksi, output panjang, respons upstream lambat | Pastikan dulu apakah permintaan sudah dijalankan atau ditagihkan; coba ulang hanya jika idempoten |
Kunci triase 5 jenis kesalahan: bedakan “mencoba ulang” dan “beralih”
Mencoba ulang berarti mengirim kembali permintaan melalui model dan jalur yang sama. Cara ini cocok untuk mengatasi gangguan sesaat. Beralih berarti mengganti model atau jalur, dan cocok ketika salah satu upstream terus-menerus tidak tersedia. Konsekuensinya berbeda: mencoba ulang menambah latensi dan berisiko menimbulkan tagihan ganda, sedangkan beralih bisa mengubah kualitas output, kompatibilitas pemanggilan tool, dan biaya.
Karena itu, urutan triase terdiri dari tiga langkah: tentukan jenis kesalahan, periksa apakah permintaan bersifat idempoten, lalu pilih antara mencoba ulang, beralih, atau berhenti. Melewatkan langkah kedua paling berisiko: menjalankan kembali pemanggilan tool yang sudah dieksekusi bisa berdampak lebih dari sekadar “mengeluarkan biaya tambahan”.
Mengapa “coba ulang semuanya” justru memperparah kesalahan API model
Kesimpulannya: mencoba ulang setiap kesalahan mungkin terlihat aman, tetapi sebenarnya bisa meningkatkan biaya, efek samping, dan pembatasan laju sekaligus. Di lingkungan produksi, insiden akibat logika semacam ini sering kali lebih sulit ditelusuri daripada kesalahan awalnya.
Masalah pertama adalah biaya ganda. Respons streaming yang terputus tidak selalu berarti permintaan gagal. Penyedia layanan mungkin sudah menghasilkan sebagian token dan mengenakan biaya untuknya. Mengirim ulang permintaan tanpa memastikan statusnya sama saja dengan membayar dua kali untuk tugas yang sama, terutama jika output-nya panjang.
Masalah kedua adalah eksekusi ganda. Dalam skenario agent, satu permintaan model bisa memicu penulisan ke database, pengiriman pesan, pembuatan tugas, bahkan pembayaran. Jika terjadi timeout saat pemanggilan alat, Anda tidak tahu apakah alat tersebut sudah dijalankan. Jika seluruh permintaan langsung dikirim ulang, bisa saja terbentuk dua pesanan atau terkirim dua email.
Masalah ketiga adalah pembatasan laju yang makin parah. Kode 429 pada dasarnya adalah pesan dari penyedia layanan untuk “memperlambat permintaan”. Jika klien langsung mencoba ulang secara bersamaan, bebannya justru bertambah. Contoh lain yang sering terjadi adalah mencoba ulang semua kesalahan 4xx: 401 awalnya muncul karena kunci API salah, tetapi setelah beberapa kali percobaan ulang, volume permintaan mencapai batas. Akhirnya, log dipenuhi 429 dan akar masalah sebenarnya malah tertutupi.
Tabel penanganan kode kesalahan 401, 429, 500, dan 529: kapan mencoba ulang atau beralih
Kesimpulan: tabel ini mencakup 14 kode status yang paling umum ditemui di lingkungan produksi. Hanya beberapa yang layak dicoba ulang; peralihan dilakukan setelah percobaan ulang terbukti tidak berhasil. Kolom “Beralih?” merujuk pada peralihan ke model atau jalur cadangan. Makna pastinya tetap bergantung pada isi respons kesalahan dan dokumentasi masing-masing penyedia.
| Kode status | Arti umum | Coba ulang? | Beralih? | Tindakan |
|---|---|---|---|---|
400 |
Format atau parameter permintaan salah | Tidak | Tidak | Perbaiki isi permintaan, periksa field dan tipenya |
401 |
Key tidak valid atau autentikasi gagal | Tidak | Tidak | Periksa Key, header permintaan Authorization, dan Base URL |
402 |
Saldo tidak cukup atau kuota habis | Tidak | Bergantung situasi | Isi saldo atau beralih ke jalur yang masih memiliki kuota, lalu kirim peringatan |
403 |
Ditolak karena izin, wilayah, atau kebijakan | Tidak | Tidak | Periksa izin akun, akses model, dan pembatasan wilayah |
404 |
Model atau endpoint tidak ditemukan | Tidak | Tidak | Periksa ID model dan path endpoint |
408 |
Permintaan melewati batas waktu | Coba ulang secara terbatas jika idempoten | Opsional | Pastikan permintaan belum dijalankan, lalu coba ulang 1 kali |
409 |
Konflik atau status tidak konsisten | Tidak | Tidak | Periksa status proses dan hindari penulisan bersamaan |
422 |
Validasi parameter gagal | Tidak | Tidak | Perbaiki parameter; sering terjadi pada schema output terstruktur |
429 |
Pembatasan laju, konkurensi, atau kuota | Coba ulang setelah backoff | Beralih jika percobaan ulang gagal | Baca isi kesalahan dan Retry-After terlebih dahulu |
500 |
Kesalahan internal upstream | Coba ulang secara terbatas | Beralih jika terus gagal | Catat request id dan isi kesalahan |
502 |
Kesalahan gateway | Coba ulang secara terbatas | Bisa beralih | Bedakan masalah gateway dan masalah upstream |
503 |
Layanan tidak tersedia | Coba ulang secara terbatas | Bisa beralih | Ikuti Retry-After, lakukan degradasi layanan jika perlu |
504 |
Gateway melewati batas waktu | Coba ulang hanya jika idempoten | Bisa beralih | Periksa dulu apakah tugas sudah dijalankan |
529 |
Upstream kelebihan beban | Coba ulang secara terbatas | Bisa beralih | Gunakan backoff dengan jitter; beralih jika kelebihan beban berlanjut |
429 tidak selalu berarti pembatasan laju: baca isi kesalahan sebelum mengambil keputusan
429 paling mudah disalahartikan. Kode ini bisa berarti pembatasan laju, batas konkurensi terlampaui, atau kuota model habis. Dalam beberapa kasus, kode ini juga berkaitan dengan saldo. Pembatasan laju biasanya pulih setelah menunggu beberapa detik dengan backoff. Namun, jika kuota habis, mencoba ulang berapa kali pun tidak akan membantu. Langsung beralih ke model termahal justru hanya menggandakan biaya tanpa menyelesaikan masalah.
Langkah penanganan 429:
- Baca
Retry-Afterdi header respons. Jika ada, tunggu sesuai durasi yang ditentukan. - Baca field jenis kesalahan dalam isi respons untuk membedakan rate limit, concurrency, dan quota.
- Jika masalahnya laju atau konkurensi: coba ulang 1 hingga 2 kali dengan backoff, lalu kurangi konkurensi lokal.
- Jika masalahnya kuota: hentikan percobaan ulang, kirim peringatan, dan beralih ke jalur yang masih memiliki kuota.
Pendekatan untuk 500 serupa. Kode ini tidak selalu berarti modelnya bermasalah; penyebabnya bisa berasal dari gateway atau upstream. Catat request id dan ringkasan isi kesalahan terlebih dahulu untuk keperluan investigasi dan rekonsiliasi.
Strategi retry saat API model mengalami error: jumlah percobaan, backoff, Retry-After, dan idempotensi
Kesimpulannya: retry hanya untuk error sementara, batasi hingga 1–2 kali, wajib menggunakan exponential backoff dengan jitter acak, dan hanya dijalankan otomatis untuk permintaan yang idempoten. Jika keempat syarat ini tidak terpenuhi, jangan lakukan retry otomatis.
| Parameter | Nilai yang disarankan | Keterangan |
|---|---|---|
| Error yang dapat di-retry | 429, 500, 502, 503, 504, 529, timeout jaringan |
Dari kelompok 4xx, hanya 408 dan 429 yang dikecualikan |
| Jumlah retry maksimum | 1–2 kali | Setelah batas tercapai, beralih ke alternatif atau kirim peringatan, jangan terus mencoba |
| Interval backoff | 1s, 2s, 4s, meningkat secara eksponensial | Tambahkan jitter acak setiap kali agar beberapa instance tidak melakukan retry bersamaan |
| Retry-After | Utamakan jika tersedia | Prioritasnya lebih tinggi daripada algoritma backoff lokal |
| Syarat idempotensi | Wajib dipenuhi | Operasi tulis, pemanggilan tool, pengiriman pesan, dan pembayaran secara default tidak di-retry otomatis |
Langkah penerapan strategi retry
- Buat fungsi klasifikasi error. Fungsi ini menerima kode status dan body error, lalu menghasilkan salah satu dari lima kategori. Dasarkan logika lain pada hasil klasifikasi ini, alih-alih memeriksa angka kode di berbagai bagian kode bisnis.
- Beri label idempotensi pada permintaan. Pembuatan teks biasa, peringkasan, dan penerjemahan umumnya dapat dianggap idempoten. Jika permintaan memicu tool atau menghasilkan operasi tulis eksternal, tandai sebagai non-idempoten.
- Periksa status permintaan non-idempoten terlebih dahulu. Setelah pemanggilan tool mengalami timeout, periksa status tugas atau database dan pastikan operasi belum dijalankan sebelum melakukan retry. Jika perlu, gunakan kunci idempotensi di sisi bisnis untuk mencegah duplikasi.
- Tetapkan batas total waktu. Total waktu retry untuk setiap permintaan harus dibatasi. Jika tidak, permintaan dari pengguna bisa saja sudah timeout sementara proses di belakang layar masih terus mencoba.
- Catat setiap percobaan. Setidaknya catat request id, ID model, kode status, kategori error, latensi, penggunaan token, dan jumlah retry.
Langkah terakhir sering dilewatkan, padahal penting untuk rekonsiliasi dan penelusuran masalah. Jika menggunakan APIYI apiyi.com, Anda dapat melihat penggunaan dan log pemanggilan berdasarkan Key di konsol. Cocokkan request id yang dicatat secara lokal dengan informasi error di platform untuk mengetahui apakah kegagalan terjadi di gateway, upstream, atau body permintaan Anda sendiri.
Tangani interupsi stream secara terpisah. Saat permintaan streaming terputus, periksa berapa banyak token yang sudah diterima dan apakah kontennya sudah bisa digunakan. Setelah itu, putuskan apakah perlu melanjutkan generasi, membuang hasil, atau mengulang permintaan. Sebelum mengulang tugas dengan output panjang, ingat bahwa generasi sebelumnya mungkin sudah dikenakan biaya.
🎯 Saran penelusuran masalah: Saat menemui error seperti
500atau529yang sulit diketahui sumbernya, simpan dulu body error asli dan request id. Lalu, periksa penggunaan dan log pada periode yang sama di konsol APIYI apiyi.com. Jangan mengambil kesimpulan hanya berdasarkan kode status.
Strategi beralih ke model cadangan: tingkatan kemampuan, pemetaan model, dan pemeriksaan kompatibilitas
Kesimpulannya: sebelum beralih, pastikan model cadangan sudah terbukti mampu menangani tugas yang sama. Jika jalur cadangan baru dicoba pertama kali saat terjadi gangguan, kemungkinan besar akan muncul kegagalan kedua.
Mulailah dengan membagi model ke dalam tiga tingkatan: flagship, serbaguna, dan ringan. Petakan setiap jenis tugas ke satu model utama dan satu model cadangan pada tingkat yang sama atau berdekatan. Jangan arahkan semua permintaan ke model termahal. Sedikit gangguan pada layanan upstream bisa membuat tagihan membengkak, sementara banyak tugas sederhana tidak mendapat manfaat dari model flagship.
| Aspek kemampuan | Model utama | Model cadangan | Kompatibel? | Yang perlu dilakukan sebelum beralih |
|---|---|---|---|---|
| Jendela konteks | Isi batas sebenarnya | Isi batas sebenarnya | Perlu diperiksa | Pastikan input nyata terpanjang dapat dimuat; jika tidak, siapkan strategi pemotongan |
| Pemanggilan tool | Skema tool, pemanggilan paralel | Sama seperti model utama | Perlu diperiksa | Validasi format pengembalian ID pemanggilan dan struktur parameter |
| Output terstruktur | JSON schema atau JSON ketat | Sama seperti model utama | Perlu diperiksa | Uji tingkat keberhasilan dengan schema yang sama untuk mencegah 422 |
| Input multimodal | Gambar, audio, video | Sama seperti model utama | Perlu diperiksa | Pastikan format input dan batas ukurannya |
| Parameter reasoning | Tingkat penalaran atau field pemikiran | Sama seperti model utama | Perlu diperiksa | Hapus atau petakan parameter yang tidak didukung saat beralih |
| Harga dan batas laju | Mengacu pada konsol | Mengacu pada konsol | Perlu diperiksa | Perkirakan biaya setelah beralih dan pastikan kuotanya mencukupi |
| Wilayah dan kepatuhan | Cakupan yang diizinkan | Cakupan yang diizinkan | Perlu diperiksa | Pastikan jalur cadangan berada dalam wilayah dan cakupan kepatuhan yang diizinkan untuk bisnis |
Sebaiknya buat satu tabel untuk setiap jenis tugas. Isi kolom “Kompatibel?” hanya dengan hasil yang sudah diverifikasi, bukan berdasarkan ingatan. Parameter reasoning paling sering menimbulkan masalah: field tingkat penalaran yang didukung model utama bisa langsung menghasilkan 400 atau 422 pada model cadangan. Logika peralihan perlu memiliki lapisan adaptasi parameter, bukan sekadar meneruskannya tanpa perubahan.
Pemetaan model: ID model mengacu pada konsol
Kesalahan dasar yang paling sering terjadi saat beralih adalah salah menulis ID model, sehingga menghasilkan 404. Sebaiknya kelola tabel pemetaan dari “nama model logis ke ID model sebenarnya”, lalu gunakan nama logis saja dalam kode aplikasi. Saat melakukan pemanggilan melalui APIYI apiyi.com, mengaculah pada konsol dan dokumentasi untuk ID yang tepat, status ketersediaan, dan harga setiap model. Gunakan https://api.apiyi.com/v1 sebagai base_url untuk integrasi. Setelah tabel pemetaan berubah, jalankan satu permintaan canary sebelum rilis.
Validasi model cadangan dan gateway multimodel: canary, log, dan penurunan otomatis
Kesimpulannya: validasi model cadangan dengan tugas nyata sebelum digunakan. Setelah beralih ke model cadangan, periksa hasilnya—jangan hanya memastikan kode statusnya 200. Gateway multimodel dapat mempermudah peralihan, tetapi tidak menggantikan pemeriksaan kualitas.
Tiga langkah validasi model cadangan
- Permintaan canary. Pilih sejumlah tugas bisnis nyata, lalu kirim petunjuk, alat, dan input yang sama ke model utama dan model cadangan.
- Bandingkan tugas yang sama. Bandingkan tingkat keberhasilan, latensi, waktu hingga token pertama, biaya token, dan tingkat kegagalan. Untuk tugas pemanggilan alat, periksa juga kompatibilitas ID pemanggilan, struktur parameter, dan struktur hasil satu per satu.
- Periksa hasil setelah peralihan. Setelah peralihan benar-benar terjadi, validasi output secara otomatis. Misalnya, periksa apakah JSON dapat diurai, semua field wajib tersedia, dan parameter alat valid. Catat juga alasan peralihan dan hasil validasinya.
Jalur peralihan ke model cadangan perlu diuji secara berkala. Misalnya, setiap minggu alihkan sebagian kecil trafik secara manual ke model cadangan untuk memastikan jalurnya masih berfungsi. Dengan begitu, dependensi, parameter, atau ID model yang tidak lagi valid bisa terdeteksi lebih awal.
Field log yang disarankan setidaknya mencakup:
- ID permintaan, ID model, endpoint, kode status, jenis error, dan ringkasan isi error
- Latensi, waktu hingga token pertama, total durasi, jumlah percobaan ulang, dan tujuan peralihan
- Token input, token output, cache hit, dan estimasi biaya
- Nama pemanggilan alat, ID pemanggilan, dan status keberhasilan eksekusi
- Alasan peralihan dan apakah hasilnya lolos validasi
Peran gateway multimodel dalam pemulihan bencana
Jika mengintegrasikan beberapa penyedia sendiri untuk pemulihan bencana, Anda setidaknya perlu mengelola beberapa Key, SDK, dan format error. Dengan gateway agregasi seperti APIYI apiyi.com, satu Key dapat digunakan untuk memanggil model populer seperti OpenAI, Claude, Gemini, DeepSeek, dan Qwen. Antarmukanya kompatibel dengan standar OpenAI serta mendukung format native Claude dan Gemini. Model utama dan cadangan dapat menggunakan kode integrasi yang sama, sehingga saat beralih Anda hanya perlu mengubah ID model, bukan seluruh jalur integrasi.
Platform ini juga menyediakan deployment multi-node, perutean cerdas, penurunan otomatis, dan load balancing untuk membantu menangani gangguan pada layanan upstream. Namun, penurunan otomatis di tingkat gateway tidak menggantikan pengambilan keputusan di tingkat aplikasi: pemeriksaan idempotensi, deduplikasi pemanggilan alat, dan validasi output tetap harus dilakukan dalam kode Anda sendiri. Pembagian tugas yang lebih aman adalah gateway menangani ketersediaan di tingkat jalur dan node, sementara aplikasi bertanggung jawab atas ketepatan hasil tugas.
💡 Saran pemulihan bencana: Saat merancang model utama dan cadangan, Anda bisa terlebih dahulu menggunakan Key yang sama di APIYI apiyi.com untuk menjalankan serangkaian tugas canary pada kedua model. Lalu, masukkan kombinasi yang lolos validasi ke tabel pemetaan model. Pengguna baru dapat memanfaatkan kuota uji coba gratis untuk validasi awal.
FAQ: Masalah Umum pada Error API Model
Intinya: lima pertanyaan berikut mencakup skenario yang paling sering diperdebatkan di lingkungan produksi. Prinsipnya sama: pahami masalahnya dulu, baru ambil tindakan.
Q1: Apakah error 401 perlu dicoba ulang?
Tidak. `401` berarti autentikasi gagal. Mencoba ulang hanya akan menambah jumlah permintaan, bahkan bisa mengubah masalah menjadi `429`. Periksa apakah Key masih valid, format header permintaan `Authorization` sudah benar, dan Base URL berasal dari platform yang sama dengan Key. Jika menggunakan APIYI apiyi.com, Anda bisa memeriksa status Key di konsol.
Q2: Apakah error 429 berarti harus langsung ganti model?
Sebaiknya jangan langsung ganti. Periksa isi error dan `Retry-After` terlebih dahulu: jika terkena batas laju atau konkurensi, biasanya cukup coba ulang 1 sampai 2 kali dengan jeda backoff; alihkan jalur hanya jika kuota habis. Saat beralih, pilih model cadangan dengan tingkat yang setara, bukan selalu model termahal.
Q3: Jika output streaming terputus, apakah permintaan perlu dijalankan ulang?
Jangan terburu-buru menjalankan ulang. Streaming yang terputus tidak selalu berarti permintaan gagal; konten mungkin sudah dihasilkan dan dikenai biaya. Periksa jumlah token yang sudah diterima dan apakah kontennya bisa digunakan: jika bisa, simpan atau lanjutkan; jika tidak bisa dan permintaannya idempoten, jalankan ulang 1 kali. Biaya aktual mengacu pada pemakaian di konsol.
Q4: Bagaimana jika pemanggilan tool dieksekusi berulang?
Solusi utamanya adalah menerapkan idempotensi di lapisan tool. Gunakan kunci idempotensi atau ID tugas dari sisi aplikasi untuk deduplikasi, sehingga setiap ID hanya dieksekusi sekali. Jika pemanggilan tool mengalami timeout, periksa status tugas terlebih dahulu dan coba ulang hanya setelah memastikan tugas belum dieksekusi. Jika sudah terjadi duplikasi, telusuri log berdasarkan ID pemanggilan, lalu lakukan kompensasi atau batalkan operasi yang berlebih.
Q5: Bagaimana jika model cadangan mengembalikan 200, tetapi hasilnya salah?
Kode 200 hanya menunjukkan bahwa permintaan berhasil, bukan berarti tugasnya berhasil. Validasi output secara otomatis, misalnya struktur JSON, field wajib, dan keabsahan parameter tool. Kegagalan validasi harus dihitung dalam tingkat kegagalan dan memicu peringatan atau peninjauan manual. Jika suatu kombinasi cadangan sering gagal memenuhi kriteria penerimaan, hapus dari tabel pemetaan dan jalankan ulang validasi canary.
Daftar periksa dan rangkuman sebelum peluncuran: kapan mencoba ulang, beralih, atau berhenti
Kesimpulannya: memeriksa daftar ini sebelum peluncuran jauh lebih andal daripada menambahkan logika secara mendadak setelah terjadi gangguan. Ingat prinsip ini: perbaiki 4xx terlebih dahulu, pertimbangkan percobaan ulang untuk 5xx, dan hentikan dulu permintaan yang tidak idempoten.
| No. | Item pemeriksaan | Kriteria lolos |
|---|---|---|
| 1 | Tentukan jenis kesalahan terlebih dahulu | Semua kode status dapat dimasukkan ke salah satu dari lima kategori; kesalahan yang tidak dikenal secara default tidak dicoba ulang |
| 2 | Jangan otomatis mencoba ulang 4xx | Untuk 400, 401, 402, 403, 404, 409, dan 422, langsung kirim peringatan atau lakukan perbaikan |
| 3 | Tentukan apakah perlu mencoba ulang atau beralih | Coba ulang hanya untuk kesalahan sementara, maksimal 1 sampai 2 kali, dengan backoff dan jitter |
| 4 | Patuhi Retry-After | Jika header respons tersedia, prioritaskan waktu tunggu yang ditentukan di dalamnya |
| 5 | Periksa idempotensi | Untuk pemanggilan tool, operasi tulis, pengiriman pesan, dan pembayaran, hentikan dulu secara default; periksa status sebelum mengambil keputusan |
| 6 | Tangani streaming yang terputus | Periksa token yang sudah diterima dan biayanya; jangan langsung mengirim ulang |
| 7 | Periksa model cadangan | Daftar kemampuan telah diisi dan diverifikasi berdasarkan jenis tugas |
| 8 | Pemetaan model | Pemetaan nama logis ke ID model sesuai dengan konsol |
| 9 | Validasi output terakhir | Setelah beralih, validasi struktur dan field, jangan hanya melihat 200 |
| 10 | Log dan simulasi | Field penting lengkap dan jalur fallback diuji secara berkala |
Poin penting penanganan kesalahan API model
- Kapan mencoba ulang: Untuk
429,500,502,503,529, dan permintaan idempoten yang mengalami timeout, coba ulang dalam jumlah terbatas dengan backoff. - Kapan beralih: Ketika percobaan ulang tetap gagal, layanan upstream terus tidak tersedia, atau kuota habis, dan model cadangan sudah diverifikasi.
- Kapan berhenti: Untuk kesalahan konfigurasi 4xx seperti
401, serta permintaan non-idempoten yang statusnya tidak diketahui. - Beralih bukan berarti berhasil: Setelah model cadangan mengembalikan 200, output tetap harus divalidasi.
- Pembagian tugas gateway dan aplikasi: Serahkan ketersediaan jalur kepada gateway, sedangkan ketepatan tugas tetap ditangani oleh kode aplikasi.
Penanganan kesalahan yang baik bukan soal seberapa agresif percobaan ulang dilakukan, melainkan apakah keputusan yang tepat diambil setiap kali terjadi kesalahan. Sebaiknya lengkapi dulu klasifikasi kesalahan, label idempotensi, dan field log, lalu perkenalkan model cadangan secara bertahap. Untuk jalur cadangan, Anda bisa mempertimbangkan APIYI apiyi.com: satu Key mencakup berbagai model populer, sehingga verifikasi dan peralihan antara model utama dan cadangan bisa dilakukan dengan kode yang sama. Harga dan ketersediaan mengacu pada konsol dan dokumentasi.
📚 Referensi
- Pusat Dokumentasi APIYI: Cara integrasi, daftar model, dan penjelasan biaya
- Tautan:
docs.apiyi.com -
Keterangan: ID model, harga, dan ketersediaan mengacu pada dokumentasi dan konsol
-
Penjelasan semantik kode status HTTP: Arti header respons standar seperti
Retry-After - Tautan:
developer.mozilla.org/docs/Web/HTTP/Status - Keterangan: Untuk memahami arti umum kode 4xx dan 5xx; arti spesifik mengacu pada isi respons kesalahan masing-masing platform model
Penulis: Tim Teknis APIYI
Diskusi teknis: Hubungi kami melalui halaman utama situs resmi APIYI di apiyi.com. Materi integrasi lainnya tersedia di pusat dokumentasi docs.apiyi.com
