Kode Error Claude API: Memperbaiki 401/403/404/429/529 Lengkap
Kode Error Claude API: Memperbaiki 401/403/404/429/529 Lengkap
Jam 2 pagi, pipeline merah seluruhnya, dan log hanya menampilkan satu baris: authentication_error. Setiap developer yang mengintegrasikan Claude API mengenal momen ini. Kabar baiknya: error API bersifat presisi — setiap kode memberi tahu persis lapisan mana yang gagal. Panduan ini membedah lima kode error Claude API yang paling sering satu per satu: artinya, mengapa muncul, perbaikan tepatnya, dan urutan troubleshooting tetap yang mengakhiri terka-tekaan.
Seperti apa bentuk error response
Definisi: API bergaya Anthropic mengembalikan JSON dengan struktur konsisten saat gagal: type level atas berisi error, error.type di dalamnya adalah kategori yang terbaca mesin (misal authentication_error), dan error.message adalah penjelasan untuk manusia. Selalu parse error.type lebih dulu — ia menunjuk titik gagal lebih presisi daripada status code saja.
{
"type": "error",
"error": {
"type": "authentication_error",
"message": "invalid x-api-key"
}
}
Detail dari pengujian nyata
Lewat gateway, kegagalan autentikasi bisa terintersepsi sebelum diteruskan, dan body-nya mungkin berupa teks pendek (contohnya 401 dengan Invalid token saja) alih-alih JSON envelope lengkap. Tes cepatnya: coba ulang sekali dengan key yang benar. Kalau berhasil, endpoint dan path aman dan kegagalan tadi ada di lapisan key.
401 authentication_error: lapisan key
Mengapa terjadi: tidak ada key, key salah ketik, key dicabut — atau variabel lingkungan lama diam-diam menimpa konfigurasi.
Cara memperbaiki: Pastikan key dikirim via header x-api-key (semantik Anthropic) tanpa spasi berlebih → jalankan echo $ANTHROPIC_API_KEY dan cek nilai shell saat ini bukan yang lama → buat key baru di console sebagai pembanding — jika yang baru berhasil, yang lama memang sudah mati.
401 yang paling serium
Meng-unset satu variabel lingkungan lama menyelesaikan lebih dari separuh kasus 401. Variabel yang diexport di shell selalu menang atas file konfigurasi — saat keduanya ada, shell yang menang.
403 permission_error: lapisan izin
Mengapa terjadi: key valid tapi tidak punya akses ke resource target — paling sering key dibatasi ke grup model tertentu, atau akun sedang ditangguhkan.
Cara memperbaiki: 403 berbeda dari 401 satu hal — "key benar tapi kurang hak". Cek dulu status akun, lalu pastikan model target masuk dalam cakupan key. Lewat gateway, periksa apakah gateway membatasi model itu; ganti model atau sesuaikan di console bila perlu.
404 not_found_error: path dan model ID
Mengapa terjadi: dua kemungkinan — path request salah, atau model ID tidak ada.
Cek path: endpoint resmi adalah https://api.anthropic.com/v1/messages; lewat EXAIV menjadi https://exaiv.com/api/ai/v1/anthropic/v1/messages. Kesalahan paling umum memakai path gaya OpenAI (/v1/chat/completions) untuk protocol Anthropic, atau kehilangan segmen /v1.
Cek model name: model: "claude-opus-4-8" yang beda satu karakter dengan ID asli langsung 404. Daftar yang tersedia adalah kebenaran sisi endpoint — katalog lengkap ada di halaman model.
429 rate_limit_error: lapisan throttle
Mengapa terjadi: laju atau concurrency melebihi kuota. Ini bukan kerusakan — ini sistem berkata "perlambat sekarang".
Cara memperbaiki: Baca hint retry-after di response dan tunggu sesuai itu → Implementasikan exponential backoff: 1 detik, lalu 2, 4, 8 dengan jitter agar klien tidak sinkron → Jangka panjang: turunkan konkurensi, gabungkan request, atau tambahkan token-bucket rate limiting di klien
429 berbeda dengan 529
429 berarti "Anda terlalu cepat" — di pihak pemanggil, diperbaiki dengan backoff. 529 berarti "pihak hulu sedang sibuk" — bukan di pihak pemanggil, diperbaiki dengan menunggu. Keduanya tidak selesai dengan retry langsung.
529 overloaded_error: hulu kelebihan beban
Mengapa terjadi: layanan hulu sementara kelebihan beban dan tidak bisa menerima request baru dalam batas waktu. Ini kode khas Claude (semantik OpenAI tidak punya padanannya) dan diteruskan apa adanya lewat endpoint kompatibel.
Cara memperbaiki: exponential backoff biasanya pulih dalam hitungan detik sampai puluhan detik. Untuk pipeline yang sensitif terhadap ketersediaan, siapkan model fallback untuk degradasi — salah satu manfaat inti gateway: mengganti model hanya mengubah satu string, tanpa key baru, tanpa kerja autentikasi ulang.
Kode lainnya sekilas
| Kode | error.type | Arti | Penanganan |
|---|---|---|---|
| 400 | invalid_request_error | Body atau parameter tidak valid | Baca message-nya; biasanya max_tokens hilang atau messages salah bentuk |
| 413 | request_too_large | Body melebihi batas ukuran | Pangkas konteks atau pecah dokumen |
| 500 | api_error | Error internal hulu | Backoff dan retry; selidiki hanya jika terus terjadi |
Urutan troubleshooting yang tetap
| Lapisan | Periksa | Alat |
|---|---|---|
| ① Key | Nilai di shell saat ini, dicabut? | echo $ANTHROPIC_API_KEY |
| ② URL | Path lengkap (dengan /v1)? | Bandingkan bagian 404 di atas |
| ③ Model ID | Cocok karakter per karakter dengan daftar | Halaman model |
| ④ Throttle/overload | Status 429/529 | Backoff dan retry |
| ⑤ Network | Proxy, firewall | Uji silang di jaringan lain |
Satu kebiasaan yang paling menghemat waktu: tembak endpoint dengan curl telanjang lebih dulu, sebelum menyentuh kode aplikasi. Jika curl berhasil dan kode Anda tidak, bug ada di lapisan klien Anda. Jika curl juga gagal, telusuri tabel di atas. Kebiasaan ini memadatkan rata-rata debugging dari setengah jam menjadi di bawah lima menit.
Bungkus sekali: request helper sadar retry
Daripada menabur logika retry di setiap titik panggil, bungkus endpoint sekali dan biarkan setiap fitur mewarisinya. Helper yang baik melakukan empat hal berurutan: kirim dengan key saat ini dan URL lengkap; klasifikasikan kegagalan menurut error.type (authentication/permission tidak untuk di-retry, rate dan overload untuk di-retry); terapkan exponential backoff dengan jitter hanya pada kelas yang bisa di-retry sampai batas percobaan maksimum; dan tampilkan error akhir beserta model ID dan jumlah percobaan agar log menjelaskan dirinya sendiri.
Tim yang mengadopsi pola ini merasakan manfaat tingkat kedua: ketika kategori error baru muncul di hulu, tabel klasifikasi ada di satu tempat, sehingga perbaikan menyebar ke semua konsumen sekaligus. Helper yang sama juga menjadi rumah alami untuk timeout budget per environment — pendek untuk jalur interaktif, longgar untuk batch — tanpa menyentuh titik panggil lagi.
Monitoring: ubah error menjadi dashboard
Menghitung error per error.type sepanjang waktu mengubah artikel ini menjadi dashboard operasional. Tiga seri cukup untuk sebagian besar tim: error autentikasi (harus datar nol — lonjakan apa pun berarti ada key bocor atau dirotasi di suatu tempat), error rate-limit (kurva perencanaan kapasitas Anda), dan 529/500 (kesehatan hulu dari sudut pandang Anda). Beri alarm pada seri pertama, ramalkan dengan seri kedua, dan panggil manusia hanya untuk kegagalan berkelanjutan pada seri ketiga.
Satu nuansa saat melalui gateway: penolakan auth milik gateway muncul sebagai 401 teks pendek alih-alih envelope JSON, jadi parse secara defensif — anggap semua non-2xx sebagai event error dan klasifikasikan dari bentuk body, bukan dari struktur yang diasumsikan. Ini menjaga dashboard jujur di jalur langsung maupun jalur gateway.
FAQ
Satu pemeriksaan tambahan: versi model dan alias
Sebagian 404 bukan karena salah ketik, melainkan karena versi model: ID dengan sufiks tanggal (misalnya snapshot tertentu) bisa dihapus saat versi baru dirilis. Jika sebuah panggilan yang kemarin berhasil hari ini menjadi 404 pada model yang sama, periksa apakah alias yang Anda pakai masih dipetakan di halaman model — dan pertimbangkan menyematkan ID keluarga model yang stabil di konfigurasi, bukan snapshot yang berumur pendek.
Kebiasaan ini bekerja dua arah: tim yang ingin mengunci perilaku juga bisa menyematkan snapshot persis, asal sadar akan siklus hidupnya. Kuncinya satu — pilih kebijakan versi secara sadar, jangan biarkan ditentukan oleh kebetulan.