Errori e modalità di guasto di Kimi K3

La forma dell'errore

Gli errori arrivano come un unico oggetto error con message, type e code:

{
  "error": {
    "message": "API key is missing or invalid",
    "type": "invalid_authentication_error",
    "code": null
  }
}

Non fare switch su code. Il campo ammette null e in tutti gli errori che abbiamo provocato su Moonshot diretto mancava del tutto. type è il campo sempre valorizzato: fai il match su quello.

Attraverso un gateway i corpi qui sotto per l'autenticazione e per «modello non trovato» non saranno identici byte per byte. Una key sbagliata viene respinta dal layer di autenticazione del gateway stesso e non arriva mai a Moonshot: leggerai la sua formulazione, non quella di Moonshot. Sintomi, cause e soluzioni restano gli stessi. Le osservazioni sul comportamento in questa pagina — la trappola del content vuoto, i parametri che non vengono validati — sono proprietà del modello e valgono ovunque venga servito K3.

{
  "error": {
    "message": "Invalid Authentication",
    "type": "invalid_authentication_error"
  }
}

Gli errori, per sintomo

{"error": {
  "message": "Invalid Authentication",
  "type": "invalid_authentication_error"
}}

{"error": {
  "message": "Not found the model kimi-k3-chat
              or Permission denied",
  "type": "resource_not_found_error"
}}

{"error": {
  "code": "model_not_found",
  "did_you_mean": "kimi-k3",
  "message": "Model 'kimi-k3-chat' is not
              available for this API key
              (unknown model id, or not
              enabled for your group). This
              error is permanent — do not
              retry with the same model id.
              Did you mean 'kimi-k3'? Call
              GET /v1/models to list the
              models available to this key."
}}

{"error": {
  "message": "Invalid request: messages
              must not be empty",
  "type": "invalid_request_error"
}}

{"error": {
  "message": "tool_choice 'specified' is
              incompatible with thinking
              enabled",
  "type": "invalid_request_error",
  "code": null
}}

{"error": {
  "message": "Rate limit exceeded",
  "type": "...",
  "code": null
}}

I guasti che non danno errore

È la categoria da mandare a memoria. K3 non valida i parametri — abbiamo trovato due casi in cui una richiesta palesemente non valida restituisce un pulito HTTP 200:

La lezione vale oltre questi due casi: un 200 da K3 non significa che la richiesta sia stata capita come volevi. Se conti su un parametro per cambiare il comportamento, verifica che il comportamento sia cambiato davvero, invece di dedurlo dall'assenza di un errore. Insieme alla trappola del content vuoto, la regola è semplice: fai le asserzioni sulla risposta, non sul codice di stato.

Una checklist prima del rilascio

1. model nella risposta riporta kimi-k3 — nessuna sostituzione silenziosa del gateway.
2. finish_reason == "stop", non "length".
3. content non è vuoto.
4. usage.total_tokens non è zero, e logghi reasoning_tokens.
5. Timeout del client in minuti, se tocchi il contesto lungo.
6. Ogni parametro su cui conti è verificato dal comportamento osservato, non da un 200.

L'asserzione che vale la pena tenere nel codice è nella guida API.

FAQ sugli errori di Kimi K3

Che cosa significa l'errore 401 Invalid Authentication di Kimi K3?

L'API key è assente, digitata male, revocata, oppure dall'header Authorization è saltato il prefisso Bearer. Il corpo è {"error": {"message": "Invalid Authentication", "type": "invalid_authentication_error"}}, senza campo code: fai il match su type, non su code.

Perché Kimi K3 restituisce 404 model not found?

L'ID del modello è esattamente kimi-k3. Il 404 diretto di Moonshot confonde un nome di modello sbagliato con un problema di permessi: recita 'Not found the model X or Permission denied'. Ritestato il 2026-07-18 via EvoLink, il corpo del 404 aggiunge un campo did_you_mean che punta a kimi-k3. Se la grafia è corretta, il problema è l'accesso o il gateway che non porta K3, non un refuso.

L'API di Kimi K3 valida i parametri della richiesta?

Non in modo affidabile. Due richieste non valide restituiscono HTTP 200 con una completion normale: reasoning_effort impostato su 'low' viene ignorato in silenzio, e max_completion_tokens impostato a 2,000,000 — quasi il doppio della finestra di contesto — viene tagliato in silenzio al tetto massimo (riverificato il 2026-07-18). Forzare una funzione specifica via tool_choice invece fallisce davvero: 400, tool_choice 'specified' is incompatible with thinking enabled. Un 200 non significa che la richiesta sia stata capita come volevi.