Fehler behandeln | transcript1 docs

Unterscheide zwischen einem abgelehnten Request und einer fehlgeschlagenen Transkription. Im ersten Fall nimmt die API den Aufruf nicht an. Im zweiten hat sie die Transkription angenommen, die Verarbeitung scheitert aber später. Dann steht status auf failed.

So liest du eine Fehlerantwort

Wenn die API einen Request unter /v1 ablehnt, bekommst du immer dieses Fehlerformat:

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

Steuere deine Fehlerbehandlung über code. message kannst du deinen Nutzern anzeigen, solltest dich aber nicht auf den Wortlaut verlassen. Er kann sich ändern. Steht retryable auf true, kann derselbe Request zu einem späteren Zeitpunkt funktionieren.

Je nach Fehler kommen neben retryable weitere Felder hinzu:

Feld	Fehlercode	Was darin steht
`action_url`	`insufficient_minutes`	Link zum Kauf eines Tarifs oder einer Minuten-Aufladung.
`minutes_needed`, `minutes_remaining`	`insufficient_minutes`	Benötigte Minuten und dein verfügbares Guthaben. Solange die benötigte Menge noch nicht feststeht, ist der erste Wert `null`.
`supported_platforms`	`unsupported_platform`	Liste der erlaubten Plattformen: `["youtube", "x", "tiktok", "instagram", "facebook", "bluesky", "twitch", "dailymotion", "pinterest", "linkedin", "snapchat"]`.
`missing_chunks`	`upload_incomplete`	Indizes der noch fehlenden Chunks.
`max_bytes`	`media_too_large`	Deine maximal erlaubte Dateigröße in Bytes.
`params`	`invalid_request`	Bei ungültigen Body- oder Query-Feldern: ein Objekt mit dem jeweiligen Feldnamen und dem zugehörigen Problem.

Wenn die API den Request ablehnt

HTTP-Status	`code`	Erneut versuchen?	Ursache und nächster Schritt
400, 422	`invalid_request`	Nein	Ein Parameter oder Body-Feld fehlt oder hat einen ungültigen Wert. Beispiele sind `diarize` mit `source: "captions"` oder `reuse_recent` mit `webhook_url`. Auch ungültiges JSON im Request-Body löst diesen Fehler aus.
422	`invalid_url`	Nein	Das Linkformat wird nicht unterstützt oder der Link passt nicht zu `platform`. Verwende YouTube, X, TikTok, Instagram, Facebook, Bluesky oder eine weitere Plattform aus Quellen und Einstellungen.
422	`unsupported_platform`	Nein	Der Wert von `platform` ist nicht erlaubt.
422	`unsupported_media`	Nein	Die Dateiendung des Uploads wird nicht unterstützt.
401	`unauthorized`	Nein	Zugangsdaten fehlen, sind ungültig, abgelaufen oder widerrufen. Auch ein ungültiges oder abgelaufenes Upload-Token führt zu diesem Fehler.
403	`insufficient_scope`	Nein	Dem OAuth-Token fehlt die Berechtigung `transcriptions:read` oder `transcriptions:write`.
403	`email_not_verified`	Nein	Deine E-Mail-Adresse ist noch nicht bestätigt. Hole das nach, bevor du eine Transkription startest.
402	`insufficient_minutes`	Nein	Du hast 0 nutzbare Minuten oder weniger, als die Transkription braucht.
402	`no_active_plan`	Nein	Für die Minuten-Aufladung fehlt ein aktiver bezahlter Tarif. Diesen Fehler liefert nur der Billing-Endpoint des Dashboards, nicht einer der Transkriptions-Endpoints.
404	`not_found`	Nein	Unter dieser ID gibt es keine Transkription, oder sie gehört zu einem anderen Team.
409	`upload_incomplete`	Nein	Lade die fehlenden Chunks hoch und rufe danach den Abschluss erneut auf.
409	`invalid_state`	Nein	Die Transkription wartet nicht auf einen Upload. Du kannst weder weitere Chunks senden noch den Upload abschließen.
409	`idempotency_conflict`	Nein	Derselbe `Idempotency-Key` wurde schon für andere Parameter verwendet.
413	`media_too_large`	Nein	Die Datei überschreitet dein Größenlimit. Die Grenzen stehen unter Dateien hochladen.
413	`invalid_request`	Nein	Der JSON-Body ist größer als 1 MB. Bei zu großen Dateien heißt der Fehler stattdessen `media_too_large`.
429	`rate_limited`	Ja	Du hast zu viele Requests pro Minute gesendet. Warte so viele Sekunden, wie `Retry-After` vorgibt.
429	`too_many_active_jobs`	Ja	Es laufen zu viele Transkriptionen oder es sind zu viele Uploads offen. Warte die in `Retry-After` angegebene Zahl von Sekunden.
500	`internal_error`	Ja	Bei uns ist ein Fehler aufgetreten. Versuche es nach einer kurzen Pause erneut.
503	`service_unavailable`	Ja	transcript1 ist gerade nicht verfügbar. Versuche es nach einer kurzen Pause erneut.

Bei Browser-Requests mit Login-Cookie statt Bearer-Zugangsdaten prüft die API zusätzlich die Herkunft. Kommt der Request von einer anderen Website, bekommst du 403 forbidden_origin. Für API-Aufrufe mit Authorization-Header gilt diese Prüfung nicht.

Bei jedem 429 steht im Header Retry-After, wie viele Sekunden du warten musst. Die konkreten Grenzen findest du unter Abrechnung und Limits.

Wann du einen Request wiederholen solltest

Wiederhole den Request nur, wenn retryable auf true steht: bei rate_limited, too_many_active_jobs, internal_error und service_unavailable. Warte die Zeit aus Retry-After ab, falls der Header vorhanden ist. Fehlt er, vergrößere die Pause zwischen den Versuchen.
Verwende bei jedem neuen Versuch für POST /v1/transcriptions denselben Idempotency-Key-Header. Hat der erste Request doch funktioniert, verhinderst du damit eine doppelte Berechnung.
Bei allen anderen Fehlercodes musst du zuerst den Request korrigieren.

Wenn die Transkription später fehlschlägt

Auch nach der API-Antwort kann die Verarbeitung noch scheitern. Hat status den Wert failed, enthält das Transkriptionsobjekt error: { "code", "message" }. Prüfe error beim Polling oder lies es im Webhook vom Typ transcription.failed.

`error.code`	Ursache	Was du tun kannst
`media_unavailable`	Das Video fehlt oder ist nicht mehr abrufbar.	Nicht unverändert wiederholen. Prüfe den Link.
`media_private`	Das Video ist als privat eingestellt.	Nicht wiederholen. Verwende einen öffentlichen Post; bei YouTube geht auch ein nicht gelistetes Video.
`login_required`	Ohne Anmeldung gibt die Plattform das Video nicht frei.	Nicht wiederholen. Der Fehler ist dauerhaft; transcript1 versucht es nicht erneut.
`no_audio`	Im Video fehlt die Tonspur.	Nicht wiederholen. Der Fehler ist dauerhaft; transcript1 versucht es nicht erneut.
`age_restricted`	Für das Video gilt eine Altersbeschränkung.	Nicht wiederholen. Lade stattdessen die Datei hoch.
`live_stream`	Der Stream läuft noch oder hat noch nicht begonnen.	Versuche es nach Ende des Streams erneut.
`no_captions`	Mit `source` auf `captions` findet transcript1 keine nutzbare Untertitelspur.	Wähle stattdessen `source: "auto"` oder `"stt"`.
`media_too_long`	Die Aufnahme überschreitet das Speech-to-Text-Limit von 5 Stunden.	Nicht unverändert wiederholen. Teile die Aufnahme auf.
`unsupported_media`	Die Datei lässt sich nicht lesen oder enthält keine Audiospur.	Nicht wiederholen. Sende eine Datei in einem unterstützten Format.
`no_speech`	transcript1 hat keine gesprochenen Worte erkannt.	Nicht wiederholen.
`unsupported_language`	Die Sprache der Aufnahme wird nicht unterstützt.	Nicht unverändert wiederholen. Setze `language` auf einen unterstützten Sprachcode oder `"auto"`.
`insufficient_minutes`	Vor der Abrechnung der Transkription waren deine Minuten aufgebraucht.	Lade Minuten auf und versuche es danach erneut.
`fetch_failed`	transcript1 konnte die Aufnahme auch nach mehreren Versuchen nicht abrufen.	Versuche es später erneut.
`transcription_failed`	Speech-to-Text ist trotz mehrerer Versuche gescheitert.	Versuche es später erneut.

Wenn eine Transkription fehlschlägt oder abgebrochen wird, zahlst du nichts. Bereits abgezogene Minuten schreiben wir dir in diesen Fällen wieder gut.