Gestire gli errori

Un errore può arrivare in due momenti. Se l'API rifiuta la chiamata, ricevi subito un errore nella risposta. Se invece accetta la trascrizione e qualcosa va storto durante l'elaborazione, ritrovi la trascrizione con status uguale a failed.

Come leggere un errore API

Quando una chiamata /v1 non viene accettata, la risposta segue sempre questa struttura:

{
  "error": {
    "code": "insufficient_minutes",
    "message": "Not enough minutes",
    "retryable": false,
    "action_url": "https://transcript1.com/dashboard/billing",
    "minutes_needed": 20,
    "minutes_remaining": 3
  }
}

Nel codice della tua applicazione, distingui gli errori usando code. Usa message solo per mostrare la spiegazione all'utente: il testo può cambiare. Con retryable uguale a true, puoi riprovare la stessa chiamata più tardi.

In alcuni casi trovi altri campi oltre a retryable:

Quando l'API rifiuta la chiamata

Se il browser si autentica con un cookie di login anziché con una credenziale bearer, controlliamo anche l'origine della chiamata. Da un altro sito ricevi 403 forbidden_origin. Il controllo non si applica alle chiamate API con l'header Authorization.

In tutte le risposte 429, l'header Retry-After indica quanti secondi aspettare. Trovi le soglie per piano in Costi e limiti.

Quando e come riprovare

• Ripeti la chiamata senza modificarla solo con retryable uguale a true: vale per rate_limited, too_many_active_jobs, too_many_live_sessions, live_capacity, internal_error, service_unavailable e per topup_needs_user con reason pending o in_progress. Aspetta i secondi di Retry-After, se presente; altrimenti aumenta l'intervallo tra i tentativi.
• Per ripetere POST /v1/transcriptions o POST /v1/topups, mantieni lo stesso Idempotency-Key. Se la prima chiamata era riuscita, eviti un secondo addebito.
• Con gli altri codici, risolvi prima il problema della chiamata.

Trascrizione live

POST /v1/live/sessions e gli altri endpoint live usano la stessa struttura di errore. Valgono anche per loro invalid_request, unsupported_language, insufficient_minutes e email_not_verified, insieme ai codici live della tabella qui sopra. Creare una sessione non è idempotente: ripetere la chiamata dopo too_many_live_sessions o live_capacity crea una nuova sessione.

Una volta creata la sessione, i problemi arrivano sul WebSocket come eventi error e codici di chiusura, non come errori HTTP. Tutti gli eventi sono in Trascrizione live.

Una sessione live che termina per un motivo come balance_exhausted o idle_timeout non è un errore: invia session.ended con un motivo di conclusione e viene salvata. Vedi Motivi di conclusione.

Quando la trascrizione non riesce

Una trascrizione può non riuscire anche dopo che l'API ha risposto alla chiamata iniziale. In quel caso ha status uguale a failed e contiene error: { "code", "message" }. Controlla error quando leggi lo stato o ricevi il webhook transcription.failed. Se una traduzione fallisce, viene inviato il webhook transcription.translation.failed e la trascrizione non fallisce mai per questo.

Se la trascrizione non riesce o la annulli, non paghi. Se avevamo già scalato dei minuti, li restituiamo al tuo saldo.