Kod Ralat Claude API: Membaiki 401/403/404/429/529 Secara Menyeluruh
Kod Ralat Claude API: Membaiki 401/403/404/429/529 Secara Menyeluruh
Pukul dua pagi, pipeline merah sepenuhnya, dan log hanya menunjukkan satu baris: authentication_error. Setiap pembangun yang mengintegrasikan Claude API mengenali saat ini. Berita baiknya: ralat API adalah tepat — setiap kod memberitahu dengan jelas lapisan mana yang gagal. Panduan ini membedah lima kod ralat Claude API yang paling kerap satu demi satu: maksudnya, sebab biasa ia berlaku, pembetulan tepat, dan turutan penyelesaian tetap yang menamatkan tekaan.
Seperti apa rupa respons ralat
Definisi: API gaya Anthropic memulangkan JSON dengan sampul konsisten apabila gagal: type peringkat atas ialah error, error.type di dalamnya ialah kategori yang boleh dibaca mesin (seperti authentication_error), dan error.message ialah penjelasan untuk manusia. Sentiasa parse error.type dahulu — ia menunjuk titik gagal lebih tepat daripada kod status semata-mata.
{
"type": "error",
"error": {
"type": "authentication_error",
"message": "invalid x-api-key"
}
}
Satu detail daripada ujian sebenar
Melalui gateway, kegagalan pengesahan boleh disekat sebelum diteruskan, dan body pada masa itu mungkin berupa teks pendek (contohnya 401 dengan Invalid token sahaja) alih-alih sampul JSON penuh. Ujian pantasnya: cuba semula sekali dengan kunci yang betul. Jika ia berjaya, endpoint dan laluan adalah betul dan kegagalan tadi berada di lapisan kunci.
401 authentication_error: lapisan kunci
Sebab berlaku: tiada kunci dilampirkan, kunci tersalah eja, kunci telah ditarik balik — atau pembolehubah persekitaran lama senyap-senyap menimpa konfigurasi anda.
Cara baiki: Sahkan kunci dihantar melalui header x-api-key (semantic Anthropic) tanpa ruang berlebihan → Jalankan echo $ANTHROPIC_API_KEY dan sahkan nilai shell semasa bukan nilai lama → Jana kunci baharu dalam konsol sebagai semakan silang — jika yang baharu berjaya, yang lama memang telah mati.
401 yang paling biasa
Menyahset satu pembolehubah persekitaran lama menyelesaikan lebih separuh daripada semua 401. Pembolehubah yang dieksport dalam shell sentiasa mengatasi fail konfigurasi — apabila kedua-duanya wujud, shell sentiasa menang.
403 permission_error: lapisan kebenaran
Sebab berlaku: kunci sah tetapi tidak ada akses ke sumber sasaran — paling kerap kunci dihadkan kepada kumpulan model tertentu, atau akaun digantung.
Cara baiki: 403 berbeza daripada 401 dalam satu perkara — "kunci betul tetapi tidak mencukupi". Sahkan status akaun dahulu, kemudian sahkan model sasaran berada dalam skop kunci. Melalui gateway, semak sama ada gateway mengehadkan model itu; tukar model atau sesuaikan dalam konsol mengikut keperluan.
404 not_found_error: laluan dan model ID
Sebab berlaku: dua kemungkinan — laluan request salah, atau model ID tidak wujud.
Semak laluan: endpoint rasmi ialah https://api.anthropic.com/v1/messages; melalui EXAIV ia menjadi https://exaiv.com/api/ai/v1/anthropic/v1/messages. Kesilapan paling biasa ialah menggunakan laluan gaya OpenAI (/v1/chat/completions) untuk protocol Anthropic, atau terlepas segmen /v1.
Semak model name: model: "claude-opus-4-8" berbeza satu aksara dengan ID sebenar ialah 404 serta-merta. Senarai yang tersedia adalah kebenaran pihak endpoint — katalog penuh ada di halaman model.
429 rate_limit_error: lapisan throttle
Sebab berlaku: kadar request atau concurrency melebihi kuota. Ini bukan kerosakan — ia sistem berkata "perlahankan sekarang".
Cara baiki: Baca hint retry-after dalam respons dan tunggu mengikutnya → Laksanakan exponential backoff: 1 saat dahulu, kemudian 2, 4, 8 dengan jitter supaya klien tidak segerak → Jangka panjang: kurangkan concurrency, gabungkan request, atau tambah token-bucket rate limiting di pihak klien
429 berbeza dengan 529
429 bermakna "anda terlalu pantas" — di pihak pemanggil, dibaiki dengan backoff. 529 bermakna "pihak hulu sibuk" — bukan di pihak pemanggil, dibaiki dengan menunggu. Kedua-duanya tidak selesai dengan cuba semula serta-merta.
529 overloaded_error: hulu terlebih beban
Sebab berlaku: perkhidmatan hulu sementara terlebih beban dan tidak dapat menerima request baharu dalam had masa. Ia kod khas Claude (semantic OpenAI tiada padanannya) dan diteruskan tidak berubah melalui endpoint serasi.
Cara baiki: exponential backoff biasanya pulih dalam beberapa saat hingga puluhan saat. Untuk saluran yang kritikal terhadap ketersediaan, konfigurasikan model sandaran untuk degradasi — salah satu manfaat utama gateway: menukar model hanyalah penukaran satu string, tanpa kunci baharu, tanpa kerja pengesahan semula.
Kod lain sekilas pandang
| Kod | error.type | Maksud | Pengendalian |
|---|---|---|---|
| 400 | invalid_request_error | Body atau parameter tidak sah | Baca message; biasanya max_tokens tiada atau messages salah bentuk |
| 413 | request_too_large | Body melebihi had saiz | Ringkaskan konteks atau pecahkan dokumen |
| 500 | api_error | Ralat dalaman hulu | Backoff dan cuba semula; siasat hanya jika berterusan |
Turutan penyelesaian: satu lapisan pada satu masa
| Lapisan | Semakan | Alat |
|---|---|---|
| ① Kunci | Nilai shell semasa, ditarik balik? | echo $ANTHROPIC_API_KEY |
| ② URL | Laluan lengkap (dengan /v1)? | Bandingkan bahagian 404 di atas |
| ③ Model ID | Padanan aksara demi aksara dengan senarai | Halaman model |
| ④ Throttle/overload | Status 429/529 | Backoff dan cuba semula |
| ⑤ Rangkaian | Proxy, firewall | Semakan silang pada rangkaian lain |
Satu tabiat yang menjimatkan masa paling banyak: hentam endpoint dengan curl kosong dahulu, sebelum menyentuh sebarang kod aplikasi. Jika curl berjaya dan kod anda tidak, bug ada di lapisan klien anda. Jika curl juga gagal, telusuri jadual di atas. Tabiat ini memampatkan purata penyahpepijatan daripada setengah jam kepada bawah lima minit.
Balut sekali: pembantu permintaan sedar retry
Daripada menabur logika cuba semula di setiap titik panggil, balut endpoint sekali dan biarkan setiap ciri mewarisinya. Pembantu yang baik melakukan empat perkara mengikut turutan: hantar dengan kunci semasa dan URL penuh; kelaskan kegagalan mengikut error.type (authentication/permission tidak untuk dicuba semula, rate dan overload untuk dicuba semula); gunakan exponential backoff dengan jitter hanya pada kelas yang boleh dicuba semula sehingga had cubaan maksimum; dan paparkan ralat akhir bersama model ID dan bilangan cubaan supaya log menerangkan dirinya sendiri.
Pasukan yang mengamalkan corak ini melaporkan manfaat kedua: apabila kategori ralat baharu muncul di hulu, jadual pengelasan berada di satu tempat, jadi pembaikan menular ke semua pengguna serentak. Pembantu yang sama juga menjadi rumah semula jadi bagi belanjawan timeout ikut persekitaran — pendek untuk laluan interaktif, longgar untuk kerana batch — tanpa menyentuh titik panggil lagi.
Pemantauan: jadikan ralat sebagai papan pemuka
Mengira ralat mengikut error.type dari masa ke masa menukar artikel ini menjadi papan pemuka operasi. Tiga siri cukup untuk kebanyakan pasukan: ralat pengesahan (patut sifar rata — sebarang lonjakan bermakna ada kunci bocor atau dirotasi di suatu tempat), ralat had-kadar (lengkung perancangan kapasiti anda), dan 529/500 (kesihatan hulu dari sudut pandangan anda). Beri amaran pada siri pertama, ramalkan dengan siri kedua, dan panggil manusia hanya untuk kegagalan berterusan pada siri ketiga.
Satu nuansa apabila melalui gateway: penolakan auth milik gateway muncul sebagai 401 teks pendek bukan sampul JSON, jadi parse secara defensif — anggap semua non-2xx sebagai peristiwa ralat dan kelaskan daripada bentuk body, bukan daripada struktur yang diandaikan. Ini memastikan papan pemuka jujur pada laluan terus dan laluan gateway.
FAQ
Semakan tambahan: versi model dan alias
Sebahagian 404 bukan kerana salah eja, tetapi kerana versi model: ID dengan akhiran tarikh (contohnya snapshot tertentu) boleh dibuang apabila versi baharu dikeluarkan. Jika panggilan yang semalam berjaya hari ini menjadi 404 pada model yang sama, semak sama ada alias yang anda gunakan masih dipetakan di halaman model — dan pertimbangkan untuk melekatkan ID keluarga model yang stabil dalam konfigurasi, bukan snapshot yang berumur pendek.
Tabiat ini berfungsi dua arah: pasukan yang mahu mengunci tingkah laku juga boleh melekatkan snapshot yang tepat, asal sedar akan kitaran hidupnya. Kuncinya satu — pilih polisi versi secara sedar, jangan biarkan ditentukan secara kebetulan.