Panduan error API AI: 401, 403, 429 & 5xx
Diagnosis masalah autentikasi, kebijakan akses, batas laju, pembatalan klien, dan kegagalan penyedia layanan pada API AI, lalu tentukan kapan percobaan ulang aman.

Error API AI paling mudah didiagnosis jika kode status diperlakukan sebagai awal penyelidikan, bukan penyebab lengkapnya. Sebelum mencoba lagi, simpan ID permintaan, stempel waktu, endpoint, model, nama kunci API, grup yang dipilih, isi respons, dan data waktu.
Tujuannya adalah mengidentifikasi lapisan mana yang menolak atau mengakhiri permintaan: klien, autentikasi, kebijakan akses, validasi protokol, perutean, backend model, atau koneksi downstream.
Arti umum kode status yang sering muncul
| Status | Interpretasi awal | Tindakan pertama |
|---|---|---|
| 400 | Bentuk permintaan, kolom, atau kontrak protokol tidak valid | Bandingkan payload dengan endpoint yang dipilih; jangan ulangi tanpa perubahan |
| 401 | Kredensial tidak ada, salah format, dinonaktifkan, kedaluwarsa, atau tidak valid | Verifikasi header Authorization dan kunci yang sedang digunakan |
| 403 | Sudah terautentikasi, tetapi diblokir oleh akun, model, grup, IP, atau kebijakan | Periksa pembatasan kunci dan akses model/grup sebelum menguji kanal |
| 404 | Path endpoint salah atau ID model tidak tersedia | Verifikasi Base URL, path, dan daftar model yang diautentikasi |
| 429 | Batas laju permintaan, kuota, atau rute yang memenuhi syarat | Periksa kuota dan batas grup; gunakan backoff terbatas atau cadangan yang dikonfigurasi |
| 499 | Klien downstream terputus atau membatalkan sebelum selesai | Periksa tenggat klien, abort, proxy, dan waktu output pertama |
| 500 | Kegagalan pemrosesan internal atau adapter | Simpan ID permintaan; coba lagi hanya jika operasi aman diulang |
| 502/503 | Respons penyedia layanan bermasalah, rute tidak tersedia, atau kendala kapasitas sementara | Periksa bukti rute dan gunakan cadangan atau percobaan ulang terbatas |
| 504 | Anggaran waktu gateway atau penyedia layanan habis | Bandingkan waktu output pertama dan total waktu dengan tenggat klien |
Interpretasi ini adalah titik awal diagnosis. Isi error dan catatan permintaan menentukan penyebab sebenarnya untuk setiap panggilan tertentu.
Diagnosis 401 sebelum mengganti model
401 biasanya terjadi sebelum perutean model yang berarti dimulai. Periksa:
- header menggunakan Authorization: Bearer ...;
- aplikasi tidak menyertakan tanda kutip, spasi, atau nilai placeholder;
- kunci aktif dan belum kedaluwarsa;
- permintaan dikirim ke host Modelflare yang dituju;
- pengelola rahasia atau deployment tidak masih menyimpan kunci lama yang sudah dirotasi.
Jangan tempelkan kunci lengkap ke log atau pesan dukungan. Jika kunci mungkin terekspos, reproduksi masalah dengan kunci uji khusus, lalu cabut kredensial yang telah bocor.
Diagnosis 403 sebagai kegagalan kebijakan akses terlebih dahulu
403 tidak otomatis berarti penyedia layanan menolak permintaan. Autentikasi dapat berhasil, sementara akses gagal sebelum pemilihan kanal karena:
- kunci membatasi model yang diminta;
- daftar IP yang diizinkan pada kunci tidak mencakup IP klien yang teramati;
- akun tidak dapat menggunakan grup model yang dipilih;
- pengguna atau kunci dinonaktifkan oleh kebijakan;
- fitur yang diminta tidak diizinkan untuk rute tersebut.
Ambil /v1/models dengan kunci yang sama, periksa batas grup dan modelnya, lalu bandingkan kode error yang persis. Jika belum ada kanal yang dipilih, mengganti kanal penyedia layanan tidak dapat memperbaiki keputusan kebijakan yang terjadi sebelumnya.
Diagnosis 429 tanpa memicu badai percobaan ulang
429 adalah sinyal kapasitas atau kebijakan, bukan instruksi untuk langsung mencoba lagi dalam loop yang rapat. Tentukan apakah batas tersebut berasal dari kuota kunci, akun, grup model, atau rute yang dipilih.
Untuk batas laju yang dapat dicoba ulang:
- patuhi Retry-After jika ada;
- gunakan backoff eksponensial dengan jitter;
- batasi jumlah percobaan dan total waktu yang berlalu;
- jaga konkurensi aplikasi dalam batas yang diketahui;
- gunakan grup cadangan berurutan hanya jika grup tersebut mempertahankan model dan protokol yang diminta.
Membuat lebih banyak kunci API belum tentu dapat melewati batas permintaan di tingkat akun atau grup.
Diagnosis 499 dari sisi pemanggil
Modelflare dapat mencatat 499 ketika koneksi klien downstream berakhir sebelum respons selesai. Mulailah dari pemanggil:
- Apakah sinyal abort terpicu?
- Apakah klien, load balancer, CDN, atau reverse proxy mencapai batas waktu idle atau total?
- Apakah pengguna menutup halaman atau menghentikan agen?
- Apakah stream menghasilkan event alat tanpa teks yang terlihat?
- Berapa lama waktu berlalu sebelum output efektif pertama?
Catatan 499 saja tidak membuktikan adanya gangguan kanal. Bandingkan permintaan lain dalam rentang waktu yang sama dan dengan model/grup yang sama sebelum mengubah kebijakan perutean.
Pisahkan kegagalan 5xx menurut lapisan
Untuk 5xx, simpan status dan detail error asli, alih-alih mengubah setiap kegagalan menjadi 500 generik di klien.
- 500 akibat validasi atau adapter dapat bersifat deterministik dan mungkin gagal lagi jika diulang tanpa perubahan.
- 502 dapat menunjukkan respons penyedia layanan yang tidak valid atau tidak lengkap.
- 503 dapat menunjukkan tidak ada rute yang memenuhi syarat atau layanan untuk sementara tidak tersedia.
- 504 menunjukkan bahwa anggaran waktu telah habis, tetapi lapisan yang bertanggung jawab masih perlu diidentifikasi.
Gunakan data waktu permintaan, grup yang dipilih, bukti kanal yang tersedia bagi tim dukungan, dan permintaan lain di sekitar waktu yang sama untuk membedakan satu respons bermasalah dari masalah rute yang berkelanjutan.
Tentukan apakah perlu mencoba lagi
| Kelas kegagalan | Keputusan percobaan ulang default |
|---|---|
| Payload tidak valid atau protokol tidak didukung | Perbaiki permintaan; jangan ulangi tanpa perubahan |
| Kunci tidak valid atau akses ditolak | Perbaiki kredensial atau kebijakan; jangan ulangi tanpa perubahan |
| Kuota habis | Tambah atau alokasikan ulang kuota secara sengaja; jangan mengulang dalam loop |
| Batas laju | Coba lagi dengan backoff terbatas jika diizinkan |
| 502/503/504 sementara | Ulangi pekerjaan idempoten dengan anggaran percobaan yang ketat |
| Pembatalan oleh klien | Coba lagi hanya jika pengguna masih membutuhkan hasilnya dan duplikasi aman |
| Efek samping alat atau operasi tulis | Wajibkan idempotensi di tingkat aplikasi sebelum mengulang |
Percobaan ulang menciptakan pekerjaan baru dan dapat menimbulkan biaya baru. Catat setiap percobaan dan jangan sembunyikan kegagalan awal di balik keberhasilan berikutnya.
Bukti yang aman untuk dicatat
Untuk dukungan atau peninjauan insiden, catat:
- ID permintaan dan stempel waktu UTC;
- endpoint dan mode streaming;
- model yang diminta dan grup yang dipilih;
- status HTTP dan kode error terstruktur;
- total waktu dan waktu output efektif pertama;
- apakah pemanggil membatalkan permintaan;
- deskripsi fitur permintaan yang sudah disanitasi, seperti alat atau input gambar.
Jangan sertakan kunci API lengkap, prompt, konten respons, isi permintaan mentah, email, atau alamat IP dalam bentuk teks biasa, kecuali proses aman yang telah disetujui secara khusus memerlukannya.
Setelah menemukan lapisan yang gagal, gunakan Perutean API AI yang andal untuk desain cadangan dan Panduan streaming untuk kegagalan event dan batas waktu.
Pertanyaan umum
Apakah 403 membuktikan bahwa penyedia sedang down?
Tidak. 403 dapat dihasilkan oleh kebijakan akun, kunci, model, grup, IP, atau fitur sebelum rute penyedia layanan dipilih. Periksa catatan permintaan dan kode error terlebih dahulu.
Apakah 499 adalah error model standar dari penyedia layanan?
Tidak. Dalam catatan permintaan Modelflare, 499 menunjukkan pembatalan downstream yang teramati sebelum permintaan selesai. Selidiki tenggat pemanggil dan proxy sebelum menganggapnya sebagai kegagalan model.
Apakah setiap respons 5xx harus dicoba ulang?
Tidak. Ulangi hanya operasi yang aman untuk diulang, gunakan anggaran percobaan dan waktu yang terbatas, serta simpan error pertama. Masalah adapter atau permintaan yang bersifat deterministik tidak akan membaik dengan pengulangan.