Anthropic API 404 not_found_error: "model: …" — perché un nome di modello esistente restituisce ancora 404

L’aspetto confuso di questo errore 404 è che il modello di solito esiste davvero: nella documentazione di Anthropic, in un post sul blog, nel codice dello scorso trimestre. Non compare però nell’elenco dei modelli che la tua chiave API è autorizzata a chiamare oggi.

L’errore

risposta (HTTP 404)

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "model: claude-3-5-sonnet"
  }
}

Cause e soluzioni in breve

Causa	Soluzione
Uno snapshot datato ritirato	Gli snapshot vengono deprecati secondo un calendario pubblicato e poi smettono di risolvere. Passa a uno snapshot attuale.
Un alias che non è mai esistito	`claude-3-5-sonnet` è una famiglia, non un id chiamabile. Gli id Anthropic includono una versione o un suffisso con la data.
Il modello esiste, ma non è abilitato per il tuo account	I modelli più recenti possono essere limitati dal livello dell'account. Il 404 è indistinguibile da un refuso: controlla l'endpoint dei modelli, non la documentazione.
Un nome di modello OpenAI su un endpoint Anthropic	`gpt-4o` su api.anthropic.com indica un modello mancante, non un errore di routing. Usa un gateway se vuoi un unico endpoint per entrambi.

Chiedi all'API, non alla documentazione

La documentazione descrive il catalogo; l'endpoint dei modelli descrive il tuo catalogo. Quando non coincidono, ha ragione l'endpoint. Qualsiasi elemento assente da questo elenco restituirà 404, per quanto attuale sembri altrove.

list-models.sh

curl -s https://api.anthropic.com/v1/models \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  | grep '"id"'

Blocca e aggiorna deliberatamente

Codificare uno snapshot datato garantisce la riproducibilità e un futuro 404 in una data che non hai scelto. Leggere l'id del modello dalla configurazione rende la correzione un valore da impostare al deploy, non una modifica al codice; lo stesso meccanismo consente il failover quando un modello è occupato anziché assente.

model_config.py

import os

# One place to change when a snapshot retires.
MODEL = os.environ.get("LLM_MODEL", "claude-sonnet-5")

resp = client.chat.completions.create(
    model=MODEL,
    messages=[{"role": "user", "content": "ping"}],
)

Distingui 404 da 400 e 403

404 significa che il nome non ha risolto nulla. 400 significa che il nome era corretto ma la richiesta no (parametro errato, contenuto malformato). 403 significa che il modello esiste ma non puoi usarlo. Solo il 404 si risolve modificando la stringa del modello.

Se chiami tramite Kunavo

Il catalogo di Kunavo è l'elenco restituito dal suo endpoint /v1/models, e ogni id al suo interno è chiamabile con qualsiasi chiave finanziata: non esiste una limitazione dei modelli per account, quindi la causa "esiste ma non è abilitato per te" descritta sopra non si verifica. Poiché lo stesso endpoint serve nomi Claude e della famiglia GPT, un id OpenAI non è nemmeno un errore di endpoint; viene semplicemente instradato. I ritiri upstream continuano a verificarsi e, quando un modello viene ritirato, il suo id viene reindirizzato o documentato invece di restituire silenziosamente 404. Gli id attuali e le relative tariffe per token sono disponibili in listino prezzi dell'API Claude.

Domande frequenti

Un 404 può mai essere un errore temporaneo?

No. A differenza di 429, 500 e 529, riprovare un 404 con la stessa stringa del modello può solo fallire di nuovo. Modifica la stringa o interrompi.

Come faccio a sapere quando uno snapshot viene ritirato?

Anthropic pubblica le date di deprecazione degli snapshot datati. Se fissi gli snapshot, quel calendario diventa un'attività da pianificare; se leggi l'id dalla configurazione, è una modifica di una riga.

Perché la chiave del mio collega funziona con lo stesso nome?

La disponibilità dei modelli può variare in base al livello dell'account. Confronta le due risposte di /v1/models: quella differenza è la risposta.

Guide correlate

Ulteriori dettagli sul significato degli errori sono disponibili in riferimento agli errori; ottenere una chiave richiede un minuto tramite registrazione e la guida all’autenticazione.