Catatan penulis: Panduan ini membantu developer menelusuri kesalahan pemanggilan API model di lingkungan produksi. Dengan membagi penyebab ke tiga lapisan—pemanggilan dari aplikasi sendiri, platform gateway, dan model upstream—kamu dapat menggunakan kode kesalahan, log, dan reproduksi minimal dengan curl untuk menentukan sumber masalah serta menyiapkan informasi saat melaporkannya.
Dini hari, notifikasi peringatan menunjukkan tingkat kesalahan pada antarmuka model meningkat. Bagian yang paling menyita waktu sering kali bukan perbaikannya, melainkan menentukan siapa yang perlu dihubungi: apakah kode aplikasi sendiri berubah dan menyebabkan masalah, apakah platform gateway bermasalah, atau apakah layanan model upstream sedang tidak stabil? Artikel ini memperkenalkan metode penentuan penyebab dalam tiga lapisan: “pemanggilan sendiri → platform gateway → model upstream” untuk mempersempit cakupan pemeriksaan dengan cepat saat pemanggilan API model gagal.
Ini bukan sekadar daftar kode kesalahan. Pembagian tiga lapisan ini juga umum digunakan oleh pengelola platform agregasi model saat menangani gangguan pemanggilan: mereka mereproduksi masalah berdasarkan parameter permintaan, log, kode kesalahan, dan rantai pemanggilan, lalu menentukan apakah sumbernya ada pada pemanggilan pengguna, kemampuan platform, atau layanan model upstream. Artikel ini mengubah pendekatan tersebut menjadi urutan pemeriksaan yang bisa langsung digunakan oleh pengguna API. Baik terhubung langsung ke penyedia maupun melalui gateway agregasi seperti APIYI, kamu bisa mengikuti urutan yang sama.
Manfaat utama: Setelah membaca artikel ini, kamu akan memahami urutan pemeriksaan 6 langkah, tanda-tanda untuk mengenali kategori kesalahan yang umum, cara membuat reproduksi minimal dengan curl, serta daftar informasi yang bisa langsung diisi saat melaporkan masalah.
Poin utama: tiga lapisan penyebab kesalahan pemanggilan API model
Setiap pemanggilan API model melewati setidaknya tiga lapisan: aplikasi dan lingkungan jaringan Anda, gateway atau platform agregasi di tengah, serta layanan model upstream yang menyediakan kemampuan inferensi. Saat terhubung langsung ke penyedia, lapisan tengahnya lebih tipis, tetapi penyeimbangan beban dan lapisan akses tetap ada. Tujuan penelusuran adalah menentukan dengan tepat di lapisan mana gangguan terjadi.
| Lapisan penyebab | Masalah yang umum | Sinyal yang sering muncul | Pihak yang bertanggung jawab |
|---|---|---|---|
| Pemanggilan Anda sendiri | Kunci salah, parameter tidak valid, melebihi konteks, pengaturan timeout lokal terlalu singkat, gangguan proksi atau DNS | 4xx muncul secara konsisten; normal setelah berganti lingkungan; hanya memengaruhi sebagian jalur kode | Anda sendiri |
| Platform gateway | Gangguan autentikasi atau penagihan, kesalahan pemetaan parameter, perutean atau fallback, pembatasan laju platform, koneksi terputus di tengah jalan | Koneksi langsung normal tetapi lewat gateway gagal; format pesan kesalahan berbeda dari upstream; beberapa model bermasalah bersamaan | Pihak platform |
| Model upstream | Layanan kelebihan beban, perubahan versi model, pergeseran kemampuan, pembatasan laju dari penyedia | Beberapa jalur akses gagal bersamaan; ada pengumuman di halaman status penyedia; hanya memengaruhi satu model | Penyedia model (biasanya disampaikan melalui platform) |
Mengapa penelusuran masalah API model perlu dimulai dari tiga lapisan ini
Saat pemanggilan API model gagal, banyak tim langsung menambah percobaan ulang atau mengganti model. Langkah ini kadang bisa menjadi solusi sementara, tetapi tanpa menemukan akar masalah, gangguan bisa muncul lagi beberapa hari kemudian. Kesalahan konfigurasi yang sebenarnya juga bisa tertutupi. Menentukan sumber masalah sebelum bertindak membantu Anda menghindari pemborosan waktu ke arah yang salah.
Pendekatan tiga lapisan juga membantu menentukan siapa yang perlu dihubungi selanjutnya. Jika masalah ada pada pemanggilan Anda sendiri, biasanya cukup perbaiki kode. Jika masalah ada pada platform gateway, hubungi pihak platform dengan menyertakan ID permintaan. Jika masalah ada pada model upstream, umumnya Anda hanya bisa menunggu pemulihan, mengganti model, atau mengaktifkan fallback. Cara penanganannya sangat berbeda, jadi diagnosis yang keliru bisa memperpanjang waktu perbaikan.
6 langkah menelusuri kesalahan pemanggilan API model
Urutan ini mengikuti prinsip “mulai dari yang murah, lalu yang mahal; isolasi masalah sebelum mendalaminya”. Setiap langkah membantu menyingkirkan satu kemungkinan, alih-alih mencurigai semua bagian sekaligus.
- Pastikan cakupan dampak: Apakah semua permintaan gagal atau hanya sebagian? Apakah hanya satu model yang terdampak atau beberapa model? Sejak kapan masalah terjadi? Semakin luas dampaknya, semakin besar kemungkinan masalah ada di platform atau penyedia upstream. Jika hanya satu fitur yang terdampak, kemungkinan besar masalahnya ada di kode Anda.
- Catat kesalahan asli: Simpan kode status HTTP, isi respons asli, ID permintaan di header respons (jika ada), waktu kejadian, dan durasinya. Jangan hanya mengandalkan informasi pengecualian yang dibungkus SDK karena banyak detail penting bisa hilang dalam prosesnya.
- Buat reproduksi minimal: Di luar kode aplikasi, gunakan curl untuk mengirim permintaan paling sederhana, misalnya satu teks pendek tanpa streaming atau pemanggilan alat. Jika permintaan minimal berhasil, kemungkinan besar masalahnya ada pada kombinasi parameter atau logika aplikasi Anda.
- Tambahkan kembali parameter secara bertahap: Mulai dari permintaan minimal, lalu tambahkan satu per satu parameter seperti petunjuk system, konteks panjang,
stream,tools, danresponse_formatsampai menemukan pemicu kegagalan. - Bandingkan dengan alternatif: Coba model lain melalui gateway yang sama, atau hubungkan langsung ke penyedia sebagai pembanding jika kondisi jaringan memungkinkan. Jika masalah hilang setelah mengganti model, biasanya penyebabnya ada di upstream. Jika koneksi langsung berhasil, biasanya masalahnya ada di gateway.
- Periksa log dan pengumuman: Lihat log pemanggilan di platform dan halaman status penyedia untuk memastikan apakah permintaan mencapai platform, apakah platform meneruskannya, dan apa respons dari upstream.
Kategori Kesalahan API Model dan Tanda-Tandanya
Kode kesalahan adalah petunjuk paling langsung untuk menelusuri masalah, tetapi pemetaan kode bisa berbeda antarplatform. Tabel berikut disusun berdasarkan makna HTTP secara umum. Untuk arti yang tepat, lihat dokumentasi platform yang Anda gunakan.
| Kategori kesalahan | Gejala umum | Tanda-tanda | Kemungkinan sumber masalah |
|---|---|---|---|
| Kegagalan autentikasi | 401 / 403 | Berhasil setelah mengganti Key; Key memiliki spasi berlebih atau digunakan di lingkungan yang salah | Biasanya pada pemanggilan sendiri, terkadang pada status akun platform |
| Kesalahan parameter | 400 / 422 | Permintaan minimal berhasil, tetapi gagal setelah parameter tertentu ditambahkan kembali; pesan kesalahan menyebutkan nama field | Pemanggilan sendiri, atau kesalahan pemetaan parameter platform |
| Model tidak ditemukan | 404 atau pesan model tidak valid | Nama model salah ketik, atau model sudah dihentikan maupun berganti nama | Pemanggilan sendiri, atau perubahan versi model |
| Pembatasan laju / kuota | 429 | Berhasil setelah jumlah permintaan bersamaan dikurangi; header respons memuat waktu tunggu sebelum mencoba lagi | Bergantung pada sumber pembatasan, bisa di lapisan platform atau upstream |
| Kesalahan server | 500 / 502 / 503 | Permintaan yang sama kadang berhasil, kadang gagal; beberapa pengguna melaporkan masalah bersamaan | Platform gateway atau model upstream |
| Timeout | 504 atau timeout dari klien | Lebih sering terjadi pada permintaan dengan output panjang; hilang setelah beralih ke streaming | Pengaturan timeout lokal, timeout gateway, atau inferensi upstream yang terlalu lambat |
| Streaming terputus | Koneksi SSE terputus di tengah jalan tanpa penanda akhir | Permintaan non-streaming normal; hanya terjadi pada jawaban panjang | Proksi perantara, kebijakan pemeliharaan koneksi gateway, atau upstream |
Kasus khusus: gangguan streaming, perubahan versi, dan fallback otomatis
Gangguan streaming adalah salah satu masalah yang paling sulit dicari penyebabnya. Klien hanya melihat koneksi terputus, sementara kode status HTTP mungkin masih 200. Saat menelusurinya, pastikan terlebih dahulu apakah proksi, load balancer, atau Nginx Anda menetapkan batas waktu idle yang terlalu singkat untuk koneksi berumur panjang. Lalu, gunakan curl dengan parameter -N untuk mengamati output SSE mentah secara langsung dan memeriksa apakah penanda akhir sudah diterima.
Perubahan versi tidak selalu menimbulkan error, tetapi dapat membuat output “berubah”, misalnya format JSON tidak lagi konsisten atau parameter pemanggilan tool tidak lengkap. Jika nama model merujuk ke alias yang terus diperbarui, perilakunya bisa berubah tanpa pemberitahuan setelah pembaruan di sisi penyedia. Untuk lingkungan produksi, sebaiknya gunakan nama model yang menyertakan tanggal atau nomor versi, lalu lakukan pengujian regresi secara berkala.
Fallback otomatis dan perutean dinamis dapat membuat hasil penelusuran masalah tidak konsisten. Beberapa gateway otomatis beralih ke jalur atau model cadangan saat layanan upstream gagal. Ini meningkatkan ketersediaan, tetapi juga dapat menyebabkan “permintaan yang sama kadang berhasil, kadang bermasalah” atau “gaya output tiba-tiba berubah”. Saat menelusurinya, periksa apakah kolom model dalam respons sesuai dengan permintaan. Jika log platform mencatat jalur atau model yang sebenarnya digunakan, periksa juga catatan tersebut. Apakah pihak pemanggil dapat mendeteksi fallback bergantung pada implementasi platform, jadi sebaiknya konfirmasikan terlebih dahulu kepada penyedia platform.
Mulai cepat mengatasi kesalahan pemanggilan API model: reproduksi minimal dengan curl
Reproduksi minimal bertujuan menyingkirkan pengaruh kode aplikasi. curl tidak bergantung pada SDK dan menampilkan interaksi HTTP mentah, sehingga cocok digunakan sebagai “bukti”. Contoh berikut menggunakan antarmuka yang kompatibel dengan OpenAI. Ganti alamatnya dengan base_url yang tercantum dalam dokumentasi platform yang kamu gunakan.
5 teknik curl untuk reproduksi minimal
- Hanya melihat kode status dan durasi: gunakan
-sS -o /dev/null -w "%{http_code} %{time_total}"untuk mengetahui dalam hitungan detik apakah permintaan sampai dan berapa lama prosesnya. - Melihat header permintaan dan respons secara lengkap: gunakan parameter
-vuntuk melihat handshake TLS, header permintaan, dan header respons. Banyak platform mencantumkan ID permintaan dan informasi pembatasan laju di header respons. - Membedakan durasi setiap tahap koneksi: tambahkan
%{time_namelookup},%{time_connect}, dan%{time_starttransfer}ke dalam-w. Jika DNS atau pembentukan koneksi lambat, biasanya masalahnya ada di jaringan lokal. Jika waktu tunggu byte pertama lama, biasanya gateway atau inferensi upstream yang lambat. - Mengamati output streaming: tambahkan
-Nuntuk menonaktifkan buffering dan atur"stream": truedi body permintaan. Amati data SSE baris demi baris untuk memastikan di mana proses terputus. - Body permintaan minimal: sisakan hanya
modeldan satu pesan dalammessagesyang berisi teks pendek, tanpa parameter opsional sepertitools,response_format, danmax_tokens.
🚀 Saran penelusuran masalah: di platform agregasi seperti APIYI, satu kunci API bisa digunakan untuk memanggil model dari berbagai penyedia. Saat melakukan reproduksi minimal, kamu hanya perlu mengubah field
modeluntuk beralih model. Dengan begitu, kamu bisa cepat membandingkan hasil antar-model tanpa menyiapkan akun dan kunci API untuk setiap penyedia.
Matriks eksperimen pembanding: tentukan lapisan sumber masalah
Masukkan reproduksi minimal ke dalam eksperimen pembanding untuk mendapatkan kesimpulan penyebab yang lebih andal. Sebaiknya jalankan setidaknya tiga kelompok pertama dalam tabel berikut.
| Kelompok eksperimen | Tindakan | Jika berhasil | Jika gagal |
|---|---|---|---|
| A: Permintaan minimal | Gunakan kunci API dan model yang sama dengan body permintaan paling sederhana | Masalah ada pada parameter aplikasi atau logika kode | Lanjutkan ke kelompok B dan C |
| B: Ganti model | Gunakan gateway dan kunci API yang sama, lalu ganti ke model dari penyedia lain | Upstream model awal mungkin bermasalah | Gateway, kunci API, atau jaringan lokal lebih patut dicurigai |
| C: Ganti lingkungan | Kirim permintaan yang sama dari mesin atau jaringan lain | Ada masalah pada jaringan lokal, proksi, atau DNS | Singkirkan faktor jaringan lokal |
| D: Perbandingan koneksi langsung | Jika memungkinkan, hubungkan langsung ke antarmuka resmi penyedia | Lapisan gateway lebih patut dicurigai; laporkan masalah ke platform | Model upstream itu sendiri bermasalah |
| E: Kurangi konkurensi | Kurangi konkurensi menjadi 1, lalu coba lagi | Masalah pembatasan laju atau kuota | Tidak terkait dengan konkurensi |
Menggunakan log pemanggilan untuk mengidentifikasi penyebab error API model
curl bisa memberi tahu apakah permintaan gagal sekarang, sedangkan log pemanggilan menunjukkan apa yang terjadi saat itu. Masalah di lingkungan produksi sering kali sulit direproduksi secara konsisten, sehingga log bisa menjadi satu-satunya sumber bukti. Saat melakukan penelusuran, cocokkan log aplikasi dengan log platform berdasarkan waktu dan ID permintaan, lalu periksa keduanya bersama-sama.
Di sisi aplikasi, catat setidaknya: waktu permintaan, nama model, ringkasan parameter (tanpa data sensitif), kode status HTTP, respons error asli, total durasi, waktu hingga byte pertama, serta ID permintaan yang dikembalikan platform. Log platform dapat melengkapi informasi yang tidak terlihat di aplikasi, seperti apakah permintaan sampai ke platform, jumlah Token yang ditagihkan, dan model yang sebenarnya dipanggil.
💡 Tips menggunakan log: Jika terhubung melalui APIYI, Anda bisa melihat riwayat pemanggilan berdasarkan rentang waktu di konsol, lalu mencocokkannya satu per satu dengan log aplikasi. Untuk mengetahui kolom apa saja yang tersedia dan apakah error asli dari penyedia hulu diteruskan, periksa penjelasan di konsol dan dokumentasi. Jika ragu, bertanya langsung kepada dukungan teknis lebih cepat daripada menebak sendiri.
Daftar informasi untuk melaporkan masalah kepada penyedia layanan
Semakin lengkap informasi yang diberikan, semakin cepat masalah bisa diselesaikan. Laporan seperti “API tidak bisa digunakan” hampir pasti akan memerlukan beberapa putaran tanya jawab. Siapkan informasi berikut agar bisa dikirim sekaligus.
| Informasi | Contoh | Kegunaan |
|---|---|---|
| Rentang waktu | Akurat hingga detik, disertai zona waktu | Memudahkan platform mencari log |
| ID permintaan | Identitas unik dalam header atau isi respons | Menemukan permintaan tertentu secara langsung |
| Nama model dan endpoint | Nama model lengkap dan jalur API | Menentukan apakah masalah terkait penyedia hulu tertentu |
| Error asli | Kode status dan isi respons lengkap | Membedakan error platform dari error penyedia hulu yang diteruskan |
| Cara reproduksi minimal | Deskripsi parameter curl yang sudah disamarkan | Membantu penyedia mereproduksi masalah secara konsisten |
| Cakupan dampak | Persentase kegagalan, model atau fitur yang terdampak | Menilai tingkat keparahan masalah |
| Pengujian pembanding yang sudah dilakukan | Hasil eksperimen kelompok A hingga E | Menghindari pemeriksaan ulang yang tidak perlu |
Sebelum melaporkan masalah, samarkan kunci API dan data pribadi pengguna. Sisakan hanya beberapa karakter awal dan akhir kunci untuk keperluan identifikasi. Jika platform menyediakan dukungan teknis 7×24 jam, untuk gangguan mendesak Anda bisa melaporkan cakupan dampaknya secara singkat terlebih dahulu, lalu melengkapi detailnya kemudian.
Pertanyaan Umum FAQ
Q1: Apa yang harus dilakukan pertama kali saat pemanggilan API model mengalami kesalahan?
Catat dulu informasi kesalahan asli, termasuk kode status, isi respons lengkap, ID permintaan, dan waktu kejadian. Lalu, pastikan cakupan dampaknya. Jangan buru-buru memulai ulang layanan atau mengubah kode. Jika kondisi awal sudah hilang, penyebabnya akan lebih sulit dilacak.
Q2: Bagaimana membedakan masalah pada gateway dan model upstream?
Cara paling efektif adalah melakukan tes perbandingan. Ganti model pada gateway yang sama. Jika kembali normal, upstream model awal lebih patut dicurigai. Jika memungkinkan, coba akses langsung ke penyedia. Jika akses langsung normal, lapisan gateway lebih patut dicurigai. Perhatikan juga format respons kesalahan: kesalahan upstream yang diteruskan biasanya memiliki struktur khas penyedia.
Q3: Jika mendapat pembatasan laju 429, apakah masalahnya pasti ada di pihak saya?
Belum tentu. Kode 429 bisa berasal dari kuota akun, batas konkurensi per Key di platform, atau beban berlebih pada upstream secara keseluruhan. Turunkan konkurensi menjadi 1 lalu coba lagi, periksa informasi pembatasan laju di header respons, dan tanyakan ke platform di lapisan mana pembatasan terjadi.
Q4: Bagaimana menelusuri permintaan yang kadang berhasil dan kadang gagal?
Periksa dulu apakah ada fallback otomatis atau perutean dinamis. Cocokkan kolom `model` dalam respons dengan kanal yang benar-benar dipanggil di log platform. Lalu, lihat distribusi durasi permintaan yang gagal. Jika banyak yang berhenti pada durasi tertentu, mungkin ada ambang batas waktu tunggu pada salah satu lapisan yang terpicu.
Q5: Bagaimana melakukan tes perbandingan antar-model dengan biaya rendah?
Platform agregasi dengan antarmuka terpadu yang mendukung banyak model bisa mempermudah pekerjaan. Di APIYI, kamu bisa berganti penyedia dengan mengubah kolom `model` menggunakan Key yang sama. Reproduksi minimal dan perbandingan antar-model bisa selesai dalam beberapa menit, tanpa perlu membuat akun di setiap penyedia.
Q6: Apakah penurunan kualitas output model secara tiba-tiba termasuk kesalahan pemanggilan?
Masalah ini tidak menghasilkan pesan kesalahan, tetapi penyebabnya tetap perlu ditelusuri. Pastikan dulu apakah nama model mengarah ke alias yang diperbarui secara berkala, lalu bandingkan hasilnya dengan hasil sebelumnya menggunakan kasus uji yang tetap. Setelah memastikan perilaku model memang berubah, laporkan ke platform beserta contoh perbandingannya.
Q7: Saat melaporkan masalah melalui gateway agregasi, apakah saya perlu memberikan informasi upstream?
Kamu tidak perlu menghubungi penyedia upstream sendiri, tetapi perlu memberikan ID permintaan, nama model, dan pesan kesalahan asli. Platform dapat menggunakan informasi tersebut untuk mencari catatan penerusan dan menentukan apakah kesalahan berasal dari upstream. Misalnya, saat menghubungi dukungan teknis APIYI, sertakan ID permintaan dan rentang waktu untuk mengurangi komunikasi bolak-balik.
Poin Penting untuk Menangani Kesalahan Pemanggilan API Model
- Tentukan lapisan sumber masalah terlebih dahulu: Periksa apakah masalah berasal dari pemanggilan Anda, platform gateway, atau model upstream sebelum menentukan solusinya.
- Simpan bukti asli: Kode status, respons asli, dan ID permintaan adalah bukti utama untuk mencari sumber masalah.
- Persempit dengan reproduksi minimal: Gunakan curl untuk mengesampingkan kode aplikasi, lalu tambahkan parameter satu per satu hingga menemukan pemicu kegagalan.
- Tentukan lapisan lewat pengujian pembanding: Coba ganti model, ganti lingkungan, dan lakukan koneksi langsung untuk mempersempit sumber gangguan.
- Waspadai fallback otomatis: Jika hasil berubah-ubah, periksa model yang benar-benar digunakan dalam respons dan catatan perutean.
- Cocokkan log dari kedua sisi: Bandingkan log aplikasi dengan log pemanggilan di platform seperti APIYI berdasarkan waktu dan ID permintaan.
- Laporkan masalah secara terstruktur: Sertakan waktu, ID permintaan, pesan kesalahan asli, dan hasil pengujian pembanding sekaligus sesuai daftar periksa.
Kesimpulan
Saat pemanggilan API model mengalami kesalahan, hal terpenting bukan langsung mencari solusi, melainkan menentukan lapisan sumber masalahnya:
- Lapisan pemanggilan Anda: Pastikan dengan reproduksi minimal dan penambahan parameter secara bertahap. Biasanya masalah bisa diselesaikan dengan mengubah kode atau konfigurasi.
- Lapisan platform gateway: Pastikan dengan pengujian koneksi langsung dan log platform, lalu hubungi penyedia platform dengan menyertakan ID permintaan.
- Lapisan model upstream: Pastikan dengan membandingkan model lain dan memeriksa pengumuman penyedia. Alihkan ke model lain atau gunakan strategi fallback untuk sementara.
Sebaiknya susun 6 langkah penanganan dan daftar periksa pelaporan masalah dalam panduan on-call tim, sehingga langkah-langkahnya bisa langsung dijalankan saat ada peringatan berikutnya. Jika Anda sedang membangun integrasi multimodel, gunakan APIYI di apiyi.com untuk menguji dan membandingkan model melalui antarmuka yang sama, lalu manfaatkan log pemanggilan platform untuk membangun alur penanganan masalah Anda sendiri.
📚 Referensi
- Kode status respons HTTP MDN: Penjelasan umum tentang makna kode status HTTP
- Tautan:
developer.mozilla.org/zh-CN/docs/Web/HTTP/Status -
Keterangan: Membantu memahami makna standar kesalahan 4xx dan 5xx
-
Manual resmi curl: Penjelasan lengkap parameter curl
- Tautan:
curl.se/docs/manpage.html -
Keterangan: Mencakup variabel durasi untuk
-wdan parameter yang umum digunakan untuk menelusuri masalah, seperti-Ndan-v -
Server-Sent Events MDN: Penjelasan protokol streaming SSE
- Tautan:
developer.mozilla.org/zh-CN/docs/Web/API/Server-sent_events - Keterangan: Membantu memahami format output streaming dan bagaimana gangguannya muncul
Penulis: Tim teknis APIYI
Diskusi teknis: Hubungi kami melalui halaman utama situs APIYI. Untuk panduan integrasi dan penelusuran masalah lainnya, kunjungi pusat dokumentasi docs.apiyi.com
