Domande frequenti

Risoluzione dei problemi

Risolvi problemi di autenticazione, modelli, streaming, attività e limiti di velocità con una checklist basata sui sintomi.

Parti dal sintomo e poi segui la soluzione. La maggior parte degli errori deriva dall'URL di base, dalla chiave, dall'ID del modello o dal saldo.

Tabella basata sui sintomi

Sintomo	Causa probabile	Soluzione
401 `UNAUTHORIZED`	Chiave mancante, errata, revocata o non inviata	Invia `Authorization: Bearer $FELO_API_KEY`; crea una nuova chiave se è stata revocata
402 `INSUFFICIENT_CREDITS`	Il saldo non copre la chiamata	Ricarica in Console Billing
404 su ogni richiesta	L'URL di base include un percorso che l'endpoint aggiunge già	Usa `https://openapi.felo.ai/api/v1` per i client OpenAI e `https://openapi.felo.ai/api` per i client Anthropic
404 su un solo modello	L'ID del modello non è pubblico oppure l'endpoint non lo serve	Controlla l'ID del modello nella pagina dei modelli e la documentazione dell'endpoint
Errore 400 su `model` o `max_tokens`	Manca un campo obbligatorio oppure il modello non accetta la struttura della richiesta	Aggiungi `max_tokens` per Messages; rimuovi i campi non supportati
429	Rate limit o limite di un provider upstream	Leggi `Retry-After`; vedi Errori, limiti e retry
5xx	Errore upstream o del servizio	Riprova con backoff; includi `request_id` se persiste
Lo stream si connette ma non invia nulla	Un proxy sta bufferizzando la risposta oppure il parser degli eventi si aspetta un formato sbagliato	Leggi lo stream in modo incrementale; disattiva il buffering delle risposte nel tuo proxy
L'attività non termina mai	Endpoint di polling sbagliato oppure uno stato terminale non gestito	Interroga l'endpoint di stato dell'attività stessa e fermati sui valori terminali
Le chiamate agli strumenti vengono ignorate	Il modello non dichiara quella capacità	Controlla `supported_parameters` nel catalogo
La Data API restituisce 404	Il prefisso `/v1/beta` è stato aggiunto due volte	Usa il percorso esattamente come scritto nel riferimento

Autenticazione

Una chiave revocata restituisce un messaggio che indica il prefisso della chiave:

{
  "status": 401,
  "code": "UNAUTHORIZED",
  "message": "API Key has been revoked (keyPrefix=...)"
}

Checklist:

L'header è Authorization: Bearer <key> per la Model API e le Felo API.
La Data API accetta anche X-API-Key: <key>.
La chiave non è racchiusa tra virgolette e non ci sono ritorni a capo finali dovuti alla copia di una variabile d'ambiente.
L'ambiente distribuito ha davvero la variabile impostata; una chiave che funziona in locale può mancare in produzione.
La chiave non è stata eliminata o ruotata. Una chiave eliminata o ruotata non può essere mostrata di nuovo; creane una nuova.

Vedi Autenticazione per la creazione delle chiavi e i limiti.

Insidie dell'URL di base

Client	URL di base corretto
SDK OpenAI	`https://openapi.felo.ai/api/v1`
SDK Anthropic	`https://openapi.felo.ai/api`
Endpoint modello grezzo	`https://openapi.felo.ai/api/v1/chat/completions`, `/responses` o `/messages`
Data API	`https://openapi.felo.ai/v1/beta`
API Felo `/v2`	`https://openapi.felo.ai/v2`

Due errori comuni:

Aggiungere /chat/completions a un URL di base che l'SDK estende già.
Impostare l'URL di base Anthropic su https://openapi.felo.ai/api/v1. L'SDK aggiunge /v1/messages, quindi la richiesta diventa /api/v1/v1/messages.

Problemi con l'ID del modello

Gli ID dei modelli sono gli ID pubblici del catalogo, non i nomi interni del provider upstream né un nome visualizzato.

Cerca l'ID nella pagina dei modelli o in GET /api/v1/models.
Verifica che il modello supporti il protocollo che stai chiamando (supported_protocols).
Se hai vincolato un canale, verifica che quel canale sia pubblicato ed eseguibile per quel modello. Un canale non disponibile non è un fallback.

Vedi Canali e routing dei provider.

Problemi di streaming

Imposta stream: true nel corpo della richiesta, non come parametro di query.
Leggi il corpo della risposta come stream. Attendere la risposta completa annulla i vantaggi dello streaming.
Alcuni proxy e piattaforme serverless bufferizzano le risposte. Disattiva il buffering per la route che fa da proxy alla richiesta.
Chat Completions trasmette choices[0].delta, non choices[0].message. Il contenuto finale arriva in molti chunk.
Uno stream può terminare senza un evento terminale pulito se la connessione cade. Tratta una connessione interrotta come risposta incompleta.

Problemi con le attività asincrone

Interroga l'endpoint di stato che appartiene alla famiglia dell'attività. I workflow Felo usano GET /v2/tasks/{task_id}/status; le attività video e immagine dei modelli usano i propri endpoint di generazione.
Fermati su ogni stato terminale, compresi errori e scadenze, non solo sul successo.
I callback di video e immagini al momento sono ignorati. Non attendere un webhook.
L'URL di un risultato può avere una validità breve. Richiedi un URL aggiornato all'endpoint di stato se un download scade.
Controlla l'attività prima di inviarla di nuovo. Inviare di nuovo un'attività in esecuzione crea un duplicato, ed entrambe vengono fatturate.

Vedi Attività asincrone.

Problemi con la Data API

Mantieni il percorso esatto del metodo dal riferimento Data API.
I corpi delle richieste sono specifici del fornitore. Un campo che funziona per un fornitore non è detto che funzioni per un altro.
Un errore del provider può arrivare dentro una risposta 4xx con un messaggio specifico del provider. Registra request_id e il corpo della risposta.

Promemoria di sicurezza

Non inserire mai una chiave API nel codice del browser, in un bundle di app mobile o in un repository pubblico. Tienila su un server e usa un proxy per le richieste.
Non registrare la chiave completa. Registra un prefisso se devi identificarla.
Ruota subito una chiave se potrebbe essere stata esposta.

Prima di contattare il supporto

Raccogli:

Endpoint e metodo HTTP.
Stato HTTP, code e request_id.
ID del modello o ID dell'attività.
Timestamp con fuso orario.
Un corpo di richiesta minimo con i segreti rimossi.

Inviali al supporto insieme all'email dell'account. Non includere la chiave API completa.