Fatturazione ed errori OpenAPI

Questa pagina si applica a /api/v1/data/*, le API esclusive della piattaforma Felo OpenAPI. Le chiamate usano il saldo della piattaforma, un saldo di crediti di servizio denominato in USD. Non consumano i crediti Felo Pro. Le API Felo più vecchie sotto /v2 usano i crediti Pro.

Leggi i prezzi attuali

curl -sS https://openapi.felo.ai/api/v1/data/prices

Questo endpoint pubblico non richiede una chiave. Abbina le sue voci per ID operazione e leggi la tariffa corrente e l'unità di fatturazione; non presumere che ogni operazione costi lo stesso né bloccare nella tua applicazione una tariffa presa da un esempio.

Una query di stato gratuita non rende gratuita la generazione o esportazione sottostante. Per X, la paginazione e i record annidati restituiti possono aumentare l'utilizzo fatturabile.

Saldo e riserve

Prima dell'esecuzione, il servizio può riservare abbastanza saldo per l'operazione. Il lavoro completato con successo viene saldato rispetto a quella riserva; il fallimento confermato la rilascia. Per i task asincroni, restituire un ID non significa che la fatturazione sia già definitiva.

La tariffazione per pagina PPT riserva dieci pagine alla creazione. La generazione riuscita effettua il saldo dell'output effettivo e rilascia i fondi inutilizzati. Generazione ed esportazione sono addebiti separati. Vedi il workflow PPT per il comportamento della riesportazione.

Se l'esecuzione o il saldo non sono certi, una riserva può rimanere in sospeso mentre il servizio la riconcilia. Non trattare ogni timeout o 5xx come prova che non sia stato fatto alcun lavoro o che una richiesta ripetuta sia gratuita.

Esamina il saldo disponibile e l'utilizzo in Console Billing. Per indicazioni sulla ricarica a livello di account, vedi Fatturazione e crediti.

Interroga l'utilizzo del wallet tramite l'API

I proprietari dell'account possono ispezionare i record delle chiamate del wallet usando un token di accesso Felo. Questa credenziale è diversa dalla API Key usata per le chiamate Data API; non sostituire FELO_API_KEY.

curl -sS 'https://openapi.felo.ai/api/wallet/usage?call_type=data' \
  -H 'Authorization: Bearer YOUR_FELO_LOGIN_TOKEN'

I record si trovano in data.items; call_type=data filtra le chiamate di funzionalità. Confronta l'utilizzo con i prezzi correnti dell'account. La lettura dei record non invia un altro task di generazione. Console Billing resta disponibile per la revisione dell'account e le ricariche.

Leggi gli errori in modo difensivo

Controlla prima lo stato HTTP. Gli errori possono usare una di queste forme; i valori qui sotto sono illustrativi:

{"error":{"code":"invalid_parameter","message":"Check the request fields"},"request_id":"example-request-id"}

{"status":402,"code":"INSUFFICIENT_BALANCE","message":"Insufficient balance","request_id":"example-request-id"}

Leggi error.code / error.message quando presenti, altrimenti code / message. Conserva request_id quando restituito. Le risposte riuscite variano in base all'operazione; non forzarle tutte nello stesso envelope di errore o data.

Decidi cosa fare dopo

execution_unconfirmed (409) e billing_settlement_pending (503) richiedono particolare attenzione: non reinviare subito il lavoro a pagamento. Interroga i task noti o contatta il supporto con il request ID. Uno stato HTTP riuscito con un risultato vuoto è diverso da una risposta di errore.

Ripeti senza creare lavoro duplicato

• Per le query di stato dei task e dello stato esportazione in sola lettura, usa un backoff limitato e rispetta Retry-After quando presente.
• Per una richiesta di creazione fallita con un task_id salvato, interroga quel task prima di crearne un altro.
• Se la connessione è fallita prima che tu ricevessi un ID, l'esito può essere sconosciuto. Non assumere che l'invio di nuovo deduplicherà la richiesta.
• Per 429, distingue un limite di frequenza breve da una finestra di quota della API key; ripetere il retry non può azzerare la quota.
• Ferma i retry dopo una scadenza configurata e mostra un errore azionabile al chiamante.

Per il supporto, fornisci endpoint, ora approssimativa, stato HTTP e request ID. Non includere mai la chiave API completa.