Mga Error Code ng Claude API: Pag-aayos ng 401/403/404/429/529 Kumpleto
Mga Error Code ng Claude API: Pag-aayos ng 401/403/404/429/529 Kumpleto
Alas-dos ng madaling araw, pula ang buong pipeline, at isang linya lang sa log: authentication_error. Pamilyar na eksena ito sa bawat developer na nag-i-integrate ng Claude API. Mabuting balita: presiso ang mga API error — bawat code ay nagsasabi kung aling layer ang bumagsak. Binubuhat ng gabay na ito nang isa-isa ang limang pinakamadalas na error code: ang kahulugan ng bawat isa, kung bakit ito bumabagsa, ang eksaktong ayos, at nakatakdang troubleshooting order na tatapos sa paghula.
Ano itsura ng error response
Kahulugan: Nagbabalik ang mga Anthropic-style API ng consistent JSON envelope kapag nabigo: ang top-level type ay error, ang panloob na error.type ay machine-readable na kategorya (tulad ng authentication_error), at ang error.message ay ipinapaliwanag para sa tao. Basahin laging ang error.type — mas tumpak nitong tinutukoy ang pagkabigo kaysa status code lang.
{
"type": "error",
"error": {
"type": "authentication_error",
"message": "invalid x-api-key"
}
}
Isang detalye mula sa live na pagsubok
Sa pamamagitan ng gateway, maaaring ma-intercept ang auth failures bago pa ma-forward, at posibleng maikling plain text ang body (halimbawa, 401 na may Invalid token lang) sa halip na buong JSON envelope. Mabilisang test: mag-retry nang isang beses gamit ang kilalang gumaganang key. Kung pumasa, ayos ang endpoint at path at nasa key layer ang naunang pagkabigo.
401 authentication_error: ang key layer
Bakit bumabagsa: walang kalakip na key, mali ang spelling, na-revoke na ang key — o lumang environment variable ang tahimang nagtatapat sa config mo.
Paano ayusin: Kumpirmahing napapadala ang key sa x-api-key header (Anthropic semantics) nang walang sobrang spaces → Patakbuhin ang echo $ANTHROPIC_API_KEY at tingnan kung luma ang value sa kasalukuyang shell → Gumawa ng panibagong key sa console bilang cross-check — kung pumasa ang bago, tunay na patay na ang luma.
Ang pinakakaraniwang 401 sa lahat
Ang pag-unset ng isang lumang environment variable ay nag-aayos sa mahigit kalahati ng lahat ng 401. Ang mga shell-exported variables ay laging tatalo sa config files — kapag parehong umairal, ang shell ang mananalo.
403 permission_error: ang permission layer
Bakit bumabagsa: tama ang key pero walang access sa target resource — pinakakaraniwan, nakarestrict ang key sa ilang model group, o suspended ang account mismo.
Paano ayusin: Naiiba ang 403 sa 401 sa isang bagay — "tama ang key pero kulang ang pahintulot". Kumpirmahin muna ang account status, saka kumpirmahing nasa saklaw ng key ang target na modelo. Sa pamamagitan ng gateway, tingnan kung may restriction ang gateway sa modelong iyon; magpalit ng modelo o i-adjust sa console kung kailangan.
404 not_found_error: path at model ID
Bakit bumabagsa: dalawang posibilidad — mali ang request path, o wala ang model ID.
Path check: ang opisyal na endpoint ay https://api.anthropic.com/v1/messages; sa EXAIV ito ay https://exaiv.com/api/ai/v1/anthropic/v1/messages. Pinakakaraniwang pagkakamali: paggamit ng OpenAI-style na paths tulad ng /v1/chat/completions sa Anthropic protocol, o pagkawala ng /v1 segment.
Model name check: ang model: "claude-opus-4-8" na magkaiba ng isang character sa totoong ID ay 404 agad. Ang available na listahan ay katotohanan ng endpoint side — buong catalog nasa models page.
429 rate_limit_error: ang throttle layer
Bakit bumabagsa: lumagpas sa quota ang request rate o concurrency. Hindi ito sira — paalala ng sistema na "bumagal ka muna ngayon".
Paano ayusin: Basahin ang retry-after hint sa response at maghintay ayon dito → I-implement ang exponential backoff: 1 segundo muna, tapos 2, 4, 8 — may jitter para hindi sabay-sabay ang mga client → Pang-matagalan: babaan ang concurrency, pagsamahin ang requests, o magdagdag ng token-bucket rate limiting sa client
429 kumpara sa 529
Ang 429 ay "mabilis ka masyado" — sa caller ang responsibilidad, inaayos ng backoff. Ang 529 ay "busy ang upstream" — hindi sa caller, inaayos ng paghihintay. Walang dalawa sa dalawang ito na aayos sa agarang retry.
529 overloaded_error: overloaded ang upstream
Bakit bumabagsa: pansamantalang overloaded ang upstream service at hindi kayang tumanggap ng mga bagong request sa loob ng time limit. Claude-specific ang code na ito (walang katumbas sa OpenAI semantics) at dumaraan nang hindi nagbabago sa mga compatible endpoint.
Paano ayusin: karaniwang babayaran ng exponential backoff sa loob ng ilang segundo hanggang ilang sampung segundo. Para sa availability-critical na pipelines, mag-set up ng fallback model para sa degradation — isa sa mga pinakamahalagang benepisyo ng gateway: ang pagpalit ng modelo ay pagbabago lang ng isang string, walang bagong keys, walang mulinang auth work.
Iba pang codes sa isang tingin
| Code | error.type | Kahulugan | Pag-aayos |
|---|---|---|---|
| 400 | invalid_request_error | Mali ang request body o parameter | Basahin ang message; kadalasang kulang ang max_tokens o mali ang messages structure |
| 413 | request_too_large | Lagpas sa size limit ang body | Paikliin ang context o hatiin ang dokumento |
| 500 | api_error | Internal error sa itaas | Backoff at retry; mag-imbestiga lang kung tuloy-tuloy |
Ang nakatakdang troubleshooting order
| Layer | Tingnan | Tool |
|---|---|---|
| ① Key | Kasalukuyang shell value, na-revoke na ba? | echo $ANTHROPIC_API_KEY |
| ② URL | Kumpleto ba ang path (may /v1)? | Pagniwa sa 404 section sa itaas |
| ③ Model ID | Character-exact laban sa listahan | Models page |
| ④ Throttle/overload | Status 429/529 | Backoff at retry |
| ⑤ Network | Proxy, firewall | Cross-check sa ibang network |
Isang gawi na nag-iipid ng pinakamaraming oras: hampasin muna ang endpoint gamit ang hubad na curl, bago dumampot sa anumang application code. Kung pumasa ang curl at hindi ang code mo, nasa client layer mo ang bug. Kung bumagsak din ang curl, lakarin ang table sa itaas. Gini-icompress nito ang average debugging mula kalahating oras hanggang mas mababa sa limang minuto.
Balutin nang isang beses: retry-aware na request helper
Sa halip na magkalat ng retry logic sa bawat call site, balutin ang endpoint nang isang beses at manahin ito ng bawat feature. Ang maayos na helper ay gumagawa ng apat na bagay nang sunod-sunod: magpadala gamit ang kasalukuyang key at buong URL; uriin ang pagkabigo ayon sa error.type (hindi nagre-retry ang authentication/permission, retryable ang rate at overload); maglapat ng exponential backoff na may jitter sa retryable na klase hanggang sa maximum na bilang ng pagtatangka; at ilabas ang huling error kasama ang model ID at bilang ng pagtatangka para ang logs ay nagpapaliwanag sa sarili.
Ang mga team na gumagamit ng pattern na ito ay nakakaranas ng pangalawang benepisyo: kapag may bagong kategorya ng error na dumarating sa itaas, nasa iisang lugar ang classification table, kaya sabay-sabay na umaabot sa lahat ng consumer ang pag-aayos. Ang parehong helper din ang likas na tahanan ng timeout budget kada environment — maikli para sa interactive na paths, maluwag para sa batch jobs — nang hindi hinahawakan muli ang mga call site.
Monitoring: gawing dashboard ang mga error
Ang pagbilang ng mga error ayon sa error.type sa paglipas ng panahon ay nagiging operational dashboard ng artikulong ito. Tatlong serye ang sapat para sa karamihan ng mga team: authentication errors (dapat flat zero — anumang spike ay may leaked o na-rotate na key sa isang lugar), rate-limit errors (ang capacity planning curve mo), at 529/500 (kalusugan ng upstream mula sa pananaw mo). I-alert ang una, i-forecast gamit ang pangalawa, at tawagan lang ang tao para sa tuloy-tuloy na pagkabigo ng pangatlo.
Isang nuance kapag dumadaan sa gateway: ang mga auth rejection ng gateway ay lumalabas bilang maikling-text na 401 sa halip na JSON envelope, kaya mag-parse nang defensive — ituring ang anumang non-2xx bilang error event at i-classify ayon sa hugis ng body, hindi sa inaasahang structure. Pinapanatili nitong tapat ang dashboard sa parehong direct at gateway paths.