Risoluzione dei problemi

Parti dal sintomo che corrisponde a ciò che vedi. In quasi tutti i casi, la scheda Logs è lo strumento di diagnosi più rapido: mostra lo stato di ogni richiesta e lo schema dell'errore (una sola chiave? un solo modello? tutto?). Consulta Attività e log.

Le richieste vengono bloccate

Ogni richiesta non riesce con 402 insufficient_credits

Causa: il modulo non è abilitato per questa struttura, oppure il saldo prepagato è esaurito (la scheda Overview mostra "Your balance is depleted. Inference requests will be blocked until you top up."). Per le chiavi API, una struttura in cui Model Router non è abilitato restituisce invece 403 "Model Router is not enabled for this facility".

Soluzione: abilita Model Router dalla pagina Welcome to Model Router (consulta Per iniziare), poi ricarica il saldo in Budgets & Limits → Balance & Top-up. Le richieste riprendono pochi istanti dopo l'accredito del saldo. Per evitare che si ripeta, attiva la ricarica automatica. Consulta Budget e ricariche.

Le richieste non riescono con 402 budget_exceeded

Causa: è stato raggiunto un limite di spesa. Il messaggio di errore indica quale finestra (giornaliera / mensile / totale) e, per quelle giornaliere e mensili, il momento esatto in cui si azzera nel fuso orario della tua struttura. Può trattarsi del limite dell'intero account oppure di un limite sulla specifica chiave o sul servizio connesso (quando il limite è circoscritto, il messaggio dice "This key's" / "This agent's").

Soluzione: attendi l'azzeramento indicato, aumenta il limite (Budgets & Limits → Spend Limits, oppure la configurazione della chiave o del servizio) oppure, per il tetto massimo totale, usa Reset hard cap. La pagina Spend Limits mostra esattamente quali limiti sono in stato "Limit reached".

Le richieste non riescono con 403 content_policy_violation

Causa: il prompt ha attivato un filtro dei contenuti in modalità block oppure la protezione contro la prompt injection.

Soluzione: controlla Settings → Guardrails. Se un'integrazione ha legittimamente bisogno di regole diverse, usa il suo interruttore Override facility guardrails invece di allentare la policy dell'intera struttura. Consulta Guardrail.

Le richieste non riescono con 429

Causa: la chiave o il servizio connesso ha superato il limite di frequenza Requests / min o Tokens / min.

Soluzione: riduci la frequenza e riprova, oppure aumenta i limiti di frequenza nella configurazione della chiave o del servizio (vuoto = illimitato). Consulta Chiavi API.

Un modello specifico restituisce errori, gli altri funzionano

Causa: il modello potrebbe essere disabilitato per la tua struttura, escluso dalla restrizione dei modelli della chiave, oppure il provider potrebbe avere dei problemi.

Soluzione: controlla Settings → Models (è abilitato?), l'elenco Restrict models della chiave e Activity → Performance → Reliability & performance by model per il tasso di errore del modello nel tempo.

Problemi con le chiavi API

401 Unauthorized

Causa: con il codice invalid_api_key ("Missing or invalid API key"), l'intestazione Authorization: Bearer … manca o non è formattata correttamente. Senza codice ("Invalid API key"), la chiave è sconosciuta (digitata male, oppure un vecchio segreto dopo una rotate) o è stata revoked.

Soluzione: verifica il formato dell'intestazione e controlla lo stato della chiave in Settings → Service Access & API Keys. Riattiva una chiave revocata, oppure aggiorna il tuo servizio con il nuovo segreto se la chiave è stata ruotata.

Ho perso il segreto della chiave

Il segreto viene mostrato una sola volta al momento della creazione e non può essere recuperato. Usa Rotate: viene emesso un nuovo segreto (mostrato una sola volta) e la chiave mantiene etichetta, limiti e cronologia. Aggiorna ogni servizio che usa la chiave: "You will need to reconfigure any services still using the old key."

La chiave funziona ma l'utilizzo compare con il nome sbagliato

Le chiavi sono identificate dalla loro Label in Activity e Logs. Modifica la chiave e imposta un'etichetta significativa; assegna a ogni sistema una chiave propria invece di condividerne una.

Problemi con gli agenti

Un agente risulta Offline

Causa: il dispositivo è spento o non ha connettività. Si tratta della connettività del dispositivo, non di un'impostazione di Model Router.

Soluzione: controlla l'alimentazione e la rete del dispositivo. La sua configurazione di accesso non viene modificata e torna a funzionare non appena il dispositivo si riconnette.

Un agente ha smesso di rispondere alle richieste AI

Controlla, in quest'ordine:

1. Saldo: un saldo esaurito blocca tutti gli agenti (l'agente mostra uno stato che richiede crediti). Ricarica il saldo.
2. Limiti per servizio: Settings → Service Access & API Keys → Connected Services: l'agente mostra "Limit reached"? Aumenta il limite o attendi che si azzeri.
3. Limiti dell'account: Budgets & Limits → Spend Limits.
4. Logs: filtra per agente per vedere l'errore effettivo sulle sue richieste.

Domande su saldo e fatturazione

I dati di spesa sembrano in ritardo

I valori Available balance e Spent today sono in tempo reale. Monthly usage viene riconciliato con il saldo ogni 15 minuti, quindi la spesa molto recente può impiegare qualche minuto per comparire. La cronologia delle transazioni elenca solo le ricariche e le rettifiche del saldo, quindi l'utilizzo non vi compare mai.

La ricarica automatica non è stata eseguita

Controlla se nella pagina Balance & Top-up c'è un banner: nessuna carta registrata, la carta richiede l'autenticazione oppure la carta è stata rifiutata. Sistema la carta (Update card / Edit payment details) oppure ricarica manualmente. I controlli della ricarica automatica vengono eseguiti all'incirca ogni 15 minuti, quindi una soglia appena superata può impiegare qualche minuto per attivarla.

Una ricarica non è riuscita

"Additional card authentication is required. Please try again.": riprova; la tua banca potrebbe chiederti una verifica. "Top-up could not be completed.": l'addebito è stato rifiutato; controlla la carta o prova con un altro importo. Nessun credito viene applicato se l'addebito non va a buon fine.

Mi è stato addebitato l'importo ma il saldo non è cambiato

Le ricariche vengono accreditate immediatamente: aggiorna la pagina. Se il saldo continua a non riflettere un addebito riuscito, annota il Transaction ID e il Payment reference dal pannello dei dettagli della transazione (o dall'estratto conto della carta) e invia una richiesta di assistenza.

Domande su registri e analisi

Una richiesta appena effettuata non compare ancora in Logs

Attiva l'aggiornamento Live (oppure fai clic su Refresh now). Di norma le richieste compaiono nel giro di pochi istanti; sotto carico possono impiegare un po' di più.

I registri mostrano un modello che non ho richiesto

Se hai inviato model: "auto", i registri mostrano il modello resolved to dall'Auto Router: apri i dettagli della richiesta per vedere Requested model: auto. È il comportamento previsto. Consulta Modelli.

Le righe mostrano "No charge"

Le risposte non riuscite o vuote che non costano nulla hanno il badge No charge: vengono registrate per completezza ma non hanno consumato saldo.

La mia esportazione CSV è più piccola del previsto

Le esportazioni grezze sono limitate a 25,000 righe: restringi l'intervallo di date oppure usa un'esportazione di riepilogo. Nota inoltre: "Summaries cover whole days, so a sub-day or graph selection is widened to full days."