Errori, limiti e tentativi

Ogni API Felo restituisce un corpo di errore JSON con un codice di errore stabile e un request ID. Leggi prima lo stato HTTP, poi il codice, poi il messaggio.

Struttura dell'errore

Le risposte attuali in produzione usano lo stato HTTP come status:

{
  "status": 401,
  "code": "UNAUTHORIZED",
  "message": "Invalid API Key",
  "request_id": "202610221444486982113280416060637185"
}

Alcuni esempi di endpoint più vecchi usano status: "error" e una stringa di codice diversa. Basa la logica sullo stato HTTP e su code, non sul testo esatto di message.

Codici comuni

I riferimenti degli endpoint elencano i codici specifici di quell'endpoint. Inizia dagli errori della Chat API o dal riferimento dell'endpoint che stai chiamando.

Endpoint di generazione dei modelli

POST /api/v1/images/generations e POST /api/v1/videos/generations restituiscono gli errori a livello di endpoint nella struttura OpenAI invece che in quella sopra:

{
  "error": {
    "message": "Model kind does not match this generation endpoint",
    "type": "invalid_request_error",
    "param": null,
    "code": "model_kind_mismatch"
  }
}

Il request ID si trova nell'header di risposta X-Request-Id, non nel corpo. Una richiesta rifiutata non crea un'attività. Una volta che un'attività esiste, la maggior parte degli errori arriva come stato terminale dell'attività in una risposta 200 anziché come errore HTTP: controlla status per failed o interrupted, poi leggi error.message. Vedi Generazione di immagini e Attività asincrone.

Request ID

I corpi di errore Felo includono request_id. Registralo insieme all'endpoint, allo stato HTTP, al codice di errore, all'ID del modello e all'ID dell'attività. Non registrare mai la chiave API completa.

La Model API accetta anche un header di richiesta facoltativo X-Request-Id. Quando ne invii uno, viene restituito in risposta per la diagnostica, così puoi correlare i tuoi log con una richiesta. Se non ne invii uno, usa il request_id restituito.

Rate limit

/v2/chat è l'unico endpoint Felo con rate limit applicati documentati:

• Per chiave API, finestra di 1 minuto.
• Per utente, finestra di 1 minuto.
• Per utente, finestra di 1 ora.

Gli utenti con un abbonamento Felo a pagamento attivo, compresi gli abbonamenti enterprise, ne sono esenti e non ricevono header X-RateLimit-*. Se lo stato dell'abbonamento non può essere verificato, i limiti si applicano comunque.

Gli altri endpoint /v2/** attualmente non hanno rate limit applicati. Le richieste alla Model API possono comunque essere limitate dal provider upstream, cosa che può manifestarsi come 429.

Non inserire limiti numerici nel codice. Leggi gli header di ogni risposta.

Politica di retry

Ciclo consigliato:

1. Riprova solo richieste idempotenti o sicure da ripetere.
2. Usa il backoff esponenziale: parti da circa 1 secondo, raddoppia e fermati a 30 secondi.
3. Aggiungi jitter casuale, così i client non riprovano tutti insieme.
4. Fermati dopo un numero ridotto di tentativi e segnala l'errore.
5. In caso di 429, rispetta Retry-After invece del tuo intervallo.

Sequenza di debug

1. Controlla che la chiave sia presente e non revocata.
2. Chiama GET /api/v1/models con la stessa chiave per confermare l'autenticazione.
3. Invia la richiesta valida più piccola all'endpoint di destinazione.
4. Aggiungi streaming, strumenti o input di grandi dimensioni uno alla volta.
5. Per il lavoro asincrono, controlla lo stato dell'attività prima di inviare di nuovo.

Correlati

• Autenticazione
• Canali e routing dei provider
• Attività asincrone
• Risoluzione dei problemi