Rangkuman kesalahan Claude Code — cara membedakan 401, 429, 529, dan kesalahan instalasi

Error Claude Code terbagi menjadi dua jenis utama, dan sebagian besar hasil pencarian hanya membahas salah satunya. Error klien pada tahap instalasi dan eksekusi, serta error API yang dikembalikan saat memanggil model, memiliki penyebab dan solusi yang sepenuhnya berbeda. Artikel ini berfokus pada jenis kedua — 401, 429, dan 529 — karena itulah error yang pertama kali ditemui saat beralih dari langganan ke API key.

String error muncul dalam bahasa Inggris di semua negara. Di bawah ini, string dibiarkan persis seperti aslinya dan hanya penjelasannya yang ditulis dalam bahasa Indonesia.

Pertama, bagi penyebab menjadi tiga dalam 30 detik

Sebelum mengubah pengaturan, kirim satu request langsung ke endpoint. Satu request ini membedakan “masalah klien / masalah autentikasi / masalah server”.

# 오류가 클라이언트 문제인지 엔드포인트 문제인지 30초 만에 가르는 방법.
# 200이 돌아오면 키와 주소는 정상이고, 남은 문제는 Claude Code 설정입니다.
curl -sS https://api.kunavo.com/v1/messages \
  -H "Authorization: Bearer sk-kn-..." \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-haiku-4-5","max_tokens":16,
       "messages":[{"role":"user","content":"ping"}]}'

401 — header salah, bukan kuncinya

Jika 401 terus terjadi meskipun Anda sudah membuat ulang kunci beberapa kali, curigai cara pengiriman, bukan nilainya. Claude Code mengirim ANTHROPIC_AUTH_TOKEN melalui header Authorization: Bearer, dan ANTHROPIC_API_KEY melalui header x-api-key. Gateway biasanya mengharapkan yang pertama, sehingga menukar kedua variabel dapat menyebabkan 401 meskipun kuncinya valid.

Kedua variabel juga sering tertinggal secara bersamaan. Hapus salah satunya, buka shell baru, lalu coba lagi. Perbedaan antarvariabel dijelaskan dalam perbedaan ANTHROPIC_AUTH_TOKEN dan ANTHROPIC_API_KEY.

429 — dua jenis 429 yang berbeda

Angkanya sama, tetapi penyebabnya sepenuhnya berbeda. Jika menggunakan langganan, Anda terkena batas jendela sesi dan tidak ada solusi selain menunggu hingga jendela direset — menaikkan paket yang lebih tinggi pun tidak membantu pada saat itu. Jika menggunakan API key, itu adalah batas jumlah request per detik atau throughput token, dan biasanya dapat diatasi dengan retry exponential backoff.

Anda dapat langsung membedakannya dengan melihat apakah ANTHROPIC_BASE_URL ditetapkan. Jika ditetapkan, Anda menggunakan key, bukan langganan. Struktur batas langganan dan pilihan setelah melampauinya dibahas dalam harga Claude Code.

529 overloaded_error — error yang bukan berasal dari Anda

529 berarti server model upstream sedang kelebihan beban sementara. Isi request, kunci, maupun saldo bukan penyebabnya, sehingga ini bukan error yang dapat dihilangkan dengan memperbaiki pengaturan. Satu-satunya tindakan adalah retry, dan exponential backoff jauh lebih berhasil daripada retry segera.

Jika menggunakan gateway dengan fallback otomatis, saat satu upstream menghasilkan 529, request dialihkan ke jalur lain sehingga frekuensi yang Anda rasakan berkurang. Penjelasan terperinci untuk pembaca berbahasa Inggris tersedia di penanganan 529 overloaded_error.

Melanjutkan pekerjaan setelah mencapai batas langganan

Jika 429 berasal dari langganan, Anda dapat mengalihkan sesi tersebut ke key alih-alih menunggu. Anda tidak perlu membatalkan langganan — selama kedua variabel di bawah ditetapkan, biaya dibebankan ke key; setelah dihapus, Anda kembali ke kondisi semula.

# Claude Code를 구독 대신 API 키로 돌릴 때 쓰는 두 줄.
# 이 두 변수가 설정돼 있는 동안에는 구독 한도가 적용되지 않습니다.
export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...

# Claude Code의 기본 모델과 opus·sonnet 별칭은 Anthropic의 최신 모델을 가리키므로,
# Kunavo가 아직 제공하지 않는 모델이 호출돼 404가 나지 않도록 모델을 고정합니다.
# sonnet 별칭이 부르는 Sonnet 5.5는 Kunavo가 제공하지 않아, 고정하지 않으면
# /model sonnet, opusplan의 실행 단계, sonnet으로 지정한 서브에이전트에서 404가 납니다.
# Opus 5.5는 Claude Code v2.1.280 이상이 필요합니다(이전 버전이면 claude update로 업데이트).
export ANTHROPIC_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5

# haiku 별칭도 고정합니다. 고정하지 않으면 Kunavo가 제공하지 않는 모델 ID(v2.1.293부터
# Haiku 5.5)를 호출해 /model haiku와 haiku로 지정한 서브에이전트에서 404가 납니다.
# 같은 줄이 백그라운드 작업도 메인 모델 대신 Haiku로 보냅니다.
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5

Tarif dibaca langsung dari katalog: Claude Sonnet 5 adalah $1,40 / $7,00 per 1M token, sedangkan Claude Haiku 4.5 adalah $0,70 / $3,50. Biaya dipotong dari saldo prabayar, sehingga tidak ada biaya pada bulan ketika Anda tidak bekerja. Metode pembayaran dan cara mendaftarkan kartu domestik dirangkum dalam harga dan pembayaran Claude API.

Error pada tahap instalasi merupakan hal terpisah

Masalah instalasi biasanya disebabkan oleh versi Node.js atau izin instalasi global, dan berbeda secara mendasar dari tiga error di atas. Pertama, pastikan claude --version menampilkan output dengan benar. Jika ya, instalasi sudah selesai dan masalah setelahnya terkait autentikasi atau jaringan. Mencampur dua jenis masalah ini akan paling banyak membuang waktu.

Pertanyaan umum