Claude Code "API Error: bad_response_status_code" — membaca status di baliknya

Error ini memberi tahu Anda bahwa panggilan gagal dan hampir tidak menjelaskan alasannya. Informasi yang berguna — kode status dan pesan provider — hanya berjarak satu debug flag, dan setiap status mengarah ke perbaikan yang berbeda.

Error

terminal

API Error: bad_response_status_code

(no status, no provider message — the wrapper hides both)

Ringkasan penyebab dan perbaikan

Penyebab	Perbaikan
401 / 403 di baliknya	Kredensial atau header tidak cocok dengan base URL khusus. Periksa variabel autentikasi yang diatur.
404 di baliknya	Id model tidak dikenal oleh host tersebut, atau base URL memiliki segmen path tambahan.
402 di baliknya	Dompet gateway kosong. Isi saldo; tidak ada yang salah dengan konfigurasi klien.
429 / 529 di baliknya	Terkena pembatasan laju atau upstream sedang penuh. Coba lagi dengan backoff, bukan dengan mengonfigurasi ulang.
Body non-JSON dengan status 200	Portal captive, proxy korporat, atau halaman error. Statusnya mungkin baik, tetapi bodynya tetap tidak dapat digunakan.

Ubah pembungkus menjadi error nyata

Output debug Claude Code mencetak permintaan dan respons upstream. Jalankan satu panggilan yang gagal dengan debug aktif dan baca baris statusnya — semua langkah setelah ini bergantung pada isinya.

debug.sh

claude --debug 2>&1 | tee claude-debug.log

grep -iE 'status|http/|error' claude-debug.log | head -20

Reproduksi panggilan yang sama dengan curl

Ambil base URL dan kredensial dari tool, lalu kirim permintaan secara langsung. Ini memisahkan "host menolak kita" dari "klien bermasalah" dalam satu langkah — dan body mentah biasanya menyebutkan masalah dalam bahasa sederhana yang dihilangkan oleh pembungkus.

reproduce.sh

curl -i "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":16,
       "messages":[{"role":"user","content":"ping"}]}'

Periksa agar base URL tidak memiliki path penutup

Claude Code menambahkan path `/v1/...` miliknya sendiri. Base URL yang sudah berakhir dengan `/v1` menghasilkan `/v1/v1/messages`, yang akan dijawab 404 oleh host mana pun — sekali lagi dibungkus sebagai bad_response_status_code. Atur hanya origin-nya.

base-url.sh

# Wrong — doubles the version segment
export ANTHROPIC_BASE_URL="https://api.kunavo.com/v1"

# Right — origin only
export ANTHROPIC_BASE_URL="https://api.kunavo.com"

Jika Anda melakukan panggilan melalui Kunavo

Untuk Kunavo, dua status yang perlu segera dikenali adalah 402 dan 401: 402 berarti dompet tidak dapat menanggung permintaan — masalahnya saldo, bukan konfigurasi — dan 401 berarti Kunavo tidak menerima kunci sk-kn- yang valid. Kunavo membaca kunci dari Authorization: Bearer atau x-api-key, jadi periksa apa yang sebenarnya dikirim Claude Code: kunci di ANTHROPIC_API_KEY memerlukan persetujuan satu kali dalam sesi interaktif dan diabaikan setelah ditolak, sedangkan ANTHROPIC_AUTH_TOKEN langsung digunakan. Kedua status tersebut dikembalikan bersama body JSON yang menyebutkan alasannya, sehingga log debug menjadi penentu, bukan sekadar petunjuk. Permintaan yang gagal tidak ditagihkan. Variabel mana yang harus diatur dan alasannya dijelaskan dalam panduan variabel autentikasi.

Pertanyaan umum

Apakah error ini pernah merupakan bug Claude Code sendiri?

Jarang. Ini adalah pembungkus tingkat transportasi: sesuatu menjawab, dan jawabannya bukan sukses. Reproduksi dengan curl menyelesaikannya — jika curl juga gagal, klien bukan masalahnya.

Ini berfungsi dengan API resmi, tetapi tidak dengan gateway saya.

Kalau begitu perbedaannya ada pada kredensial atau base URL, bukan tool. Periksa header autentikasi yang diharapkan gateway dan apakah base URL Anda sudah berisi /v1.

Haruskah saya mencoba ulang secara otomatis?

Hanya setelah Anda mengetahui statusnya. Mencoba ulang 401 atau 404 tidak ada gunanya; mencoba ulang 429 atau 529 dengan backoff adalah tindakan yang benar.

Panduan terkait

Detail semantik error lainnya tersedia di referensi error; mendapatkan kunci hanya perlu satu menit melalui pendaftaran dan panduan autentikasi.