Risoluzione dei problemi con gli URL base di OpenAI
Passare da un modello all'altro dovrebbe essere semplice. Basta cambiare l'endpoint e mantenere lo stesso SDK.
Nei progetti reali, la prima esecuzione spesso fallisce. Potresti visualizzare errori come 401, 404 o 429.
Usa questa checklist prima di dare la colpa all'SDK.
Controlla il prefisso /v1 La maggior parte dei gateway richiede il suffisso /v1 nell'URL. Se usi solo il dominio, l'SDK potrebbe chiamare il percorso errato. Copia il formato esatto dalla documentazione del provider.
Verifica le tue chiavi API Mescolare le chiavi causa fallimenti. Controlla questi errori comuni: • Usare una chiave OpenAI con un URL di relay. • Usare una chiave di relay con un URL OpenAI. • Usare una chiave di un progetto disabilitato. • Includere uno spazio all'inizio o alla fine della chiave. Se visualizzi un errore 401, stampa i primi e gli ultimi caratteri della tua chiave per confrontarli con la dashboard. Non registrare l'intera chiave nei log.
Corrispondenza esatta dei nomi dei modelli Non tirare a indovinare i nomi dei modelli. I nomi dei gateway cambiano. Un nome errato porta a errori 404 o model_not_found. Copia l'ID del modello direttamente dall'elenco dei modelli attuali.
Esegui prima una richiesta minima Prima di fare il debug dell'intera applicazione, esegui un piccolo test. Usa un semplice messaggio "ping" e un valore basso di max_tokens. Se questo funziona, l'URL, la chiave e il modello sono corretti. Il bug risiede nella logica della tua app, come lo streaming o il tool calling.
Comprendi i codici di errore • 401 indica un problema di chiave o di account. • 429 indica un problema di limite di velocità (rate limit) o di credito/saldo. Se vedi un 429, controlla la pagina di fatturazione. Evita cicli di retry troppo serrati. Peggiorano il problema.
Controlla la pagina di stato Se il tuo codice funzionava ieri ma oggi fallisce, non riscrivere l'integrazione. Controlla prima la pagina di stato del provider. Spesso la causa è un incidente a monte (upstream).
Usa un comando curl Tieni un semplice comando curl nella documentazione del tuo progetto.
Quando la tua app si rompe, esegui prima il comando curl. Se curl fallisce, il problema è l'account, il gateway o la rete. Se curl funziona, il problema è il codice della tua app.