Raccolta degli errori di Claude Code — distinguere 401, 429, 529 ed errori di installazione

Gli errori di Claude Code sono principalmente di due tipi e la maggior parte dei risultati di ricerca tratta solo uno dei due. Gli errori del client durante installazione o avvio e gli errori API restituiti quando si chiama il modello hanno cause e soluzioni completamente diverse. Questo articolo si concentra sui secondi — 401, 429 e 529 — perché sono gli errori che si incontrano per primi quando si passa da un abbonamento a una chiave API.

Le stringhe di errore compaiono in inglese in qualsiasi Paese. Di seguito lasciamo le stringhe nella loro forma originale e forniamo le spiegazioni in coreano.

Dividi prima la causa in tre categorie in 30 secondi

Prima di modificare le impostazioni, invia una richiesta diretta all'endpoint. Questa singola richiesta distingue tra «problema del client / problema di autenticazione / problema del 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 — spesso l'errore è nell'header, non nella chiave

Se il 401 continua anche dopo aver emesso più volte una nuova chiave, sospetta il modo in cui viene inviata, non il valore. Claude Code invia ANTHROPIC_AUTH_TOKEN nell'header Authorization: Bearer e ANTHROPIC_API_KEY nell'header x-api-key. I gateway si aspettano nella maggior parte dei casi il primo formato; se scambi le due variabili, otterrai un 401 anche con una chiave valida.

È comune che entrambe le variabili rimangano impostate. Rimuovine una, riapri la shell e riprova. La differenza tra le variabili è descritta in La differenza tra ANTHROPIC_AUTH_TOKEN e ANTHROPIC_API_KEY.

429 — due 429 completamente diversi

Il numero è lo stesso, ma la causa è completamente diversa. Se stai usando un abbonamento, hai raggiunto il limite della finestra di sessione e non puoi fare altro che attendere il reset; in quel momento neppure passare a un piano superiore è utile. Se stai usando una chiave API, hai raggiunto un limite di richieste al secondo o di elaborazione dei token; nella maggior parte dei casi basta ritentare con exponential backoff.

Puoi distinguere immediatamente i due casi verificando se ANTHROPIC_BASE_URL è impostato. Se lo è, stai usando una chiave e non un abbonamento. La struttura dei limiti dell'abbonamento e le opzioni disponibili dopo averli superati sono trattate in Prezzi di Claude Code.

529 overloaded_error — un errore che non dipende da te

529 significa che il server del modello upstream è temporaneamente sovraccarico. Né il contenuto della richiesta, né la chiave, né il saldo ne sono la causa, quindi non è un errore che puoi eliminare correggendo le impostazioni. L'unica risposta è ritentare; l'exponential backoff ha una percentuale di successo molto più alta rispetto al retry immediato.

Con un gateway dotato di fallback automatico, quando un upstream restituisce 529 la richiesta passa a un altro percorso, riducendo la frequenza percepita. Una spiegazione dettagliata per i lettori anglofoni è disponibile in Gestire 529 overloaded_error.

Continuare a lavorare dopo aver raggiunto il limite dell'abbonamento

Se il 429 dipende dall'abbonamento, puoi trasferire solo quella sessione a una chiave invece di attendere. Non devi annullare l'abbonamento: finché le due variabili seguenti sono impostate, la fatturazione avviene sulla chiave e, quando le rimuovi, torni al comportamento originale.

# 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

Le tariffe vengono lette direttamente dal catalogo: Claude Sonnet 5 costa $1,40 / $7,00 per 1M token, mentre Claude Haiku 4.5 costa $0,70 / $3,50. L'importo viene detratto dal saldo prepagato, quindi nei mesi in cui non lavori non sostieni costi. I metodi di pagamento e la registrazione delle carte nazionali sono descritti in Prezzi e pagamenti dell'API Claude.

Gli errori durante l'installazione sono un caso distinto

I problemi di installazione dipendono nella maggior parte dei casi dalla versione di Node.js o dai permessi per l'installazione globale e appartengono a una categoria diversa dai tre errori precedenti. Verifica prima che claude --version venga visualizzato normalmente. Se l'output è corretto, l'installazione è terminata e il problema successivo riguarda autenticazione o rete. Confondere le due categorie è il modo più rapido per perdere tempo.

Domande frequenti