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, internal_error e service_unavailable. Aspetta i secondi di Retry-After, se presente; altrimenti aumenta l'intervallo tra i tentativi.
• Per ripetere POST /v1/transcriptions, 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.

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 la trascrizione non riesce o la annulli, non paghi. Se avevamo già scalato dei minuti, li restituiamo al tuo saldo.