Error API AI: 401, 403, 429, dan 5xx
Diagnosis autentikasi, kebijakan, limit, cancellation, dan upstream per lapisan lalu tentukan percobaan ulang yang aman.
Status HTTP adalah awal diagnosis API AI, bukan seluruh penyebab. Sebelum mencoba lagi, simpan request ID, waktu UTC, endpoint, model, nama kunci, grup, error terstruktur, dan timing. Lalu tentukan apakah penolakan berasal dari klien, autentikasi, kebijakan, protokol, rute, backend, atau koneksi downstream.
Interpretasi awal
| Status | Arti pertama | Tindakan pertama |
|---|---|---|
| 400 | Payload atau kontrak tidak valid | Perbaiki, jangan ulangi tanpa perubahan |
| 401 | Kunci hilang, salah, atau kedaluwarsa | Periksa Authorization dan kunci saat ini |
| 403 | Kebijakan akun, model, grup, atau IP | Periksa batas kunci sebelum channel |
| 404 | Path atau ID model salah | Periksa Base URL dan /v1/models |
| 429 | Limit kuota, laju, atau rute | Cari lapisan limit dan lakukan backoff terbatas |
| 499 | Klien membatalkan sebelum selesai | Periksa deadline, Abort, proxy, dan output pertama |
| 502/503/504 | Upstream, ketersediaan, atau batas waktu | Simpan bukti dan coba terbatas |
Diagnosis per lapisan
401 biasanya terjadi sebelum perutean. Periksa Authorization: Bearer ..., status kunci, host, dan Secret lama pada deployment. Jangan taruh kunci lengkap di log atau tiket.
403 tidak membuktikan penolakan penyedia. Batas model, IP allowlist, hak grup, atau kebijakan akun dapat bekerja sebelum pemilihan channel. Panggil /v1/models dengan kunci yang sama dan lihat kode persis.
Untuk 429, tentukan apakah kunci, akun, grup, atau rute yang dibatasi. Patuhi Retry-After, gunakan exponential backoff dengan jitter, dan batasi percobaan, waktu, serta concurrency. Menambah kunci belum tentu melewati limit akun.
499 mencatat koneksi downstream yang berakhir. Mulai dari Abort, browser, CDN, load balancer, dan proxy; bandingkan output efektif pertama. Satu catatan tidak membuktikan channel gagal.
Keputusan mencoba lagi
- Permintaan, kunci, atau akses salah: perbaiki, jangan ulangi sama.
- Rate limit: backoff terbatas hanya bila diizinkan.
- 502, 503, 504 sementara: hanya pekerjaan idempoten dengan anggaran ketat.
- Cancellation: pastikan hasil masih dibutuhkan dan efek tidak terduplikasi.
- Alat atau operasi tulis: sediakan idempotensi aplikasi dahulu.
Setiap percobaan dapat menciptakan kerja dan biaya. Bagikan ID, waktu, endpoint, streaming, model, grup, status, kode, dan timing; jangan kunci lengkap, prompt, respons, body, email, atau IP mentah. Lanjutkan dengan panduan perutean dan streaming.