# Fehler behandeln

> So liest du API-Fehler, erkennst fehlgeschlagene Transkriptionen und entscheidest, wann sich ein neuer Versuch lohnt.

Canonical: https://transcript1.com/de/docs/errors
Language: de
Last updated: 2026-11-05

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:

```json
{
  "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`, `no_active_plan`, `topup_needs_user` | 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`. |
| `reason`, `packs` | `topup_needs_user` | Warum die Karte nicht belastet wurde, und die angefragten Pakete. |
| `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](https://transcript1.com/de/docs/sources-and-options). |
| 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 | Bestätige deine E-Mail-Adresse, bevor du Transkriptionen oder Live-Sitzungen anlegst. |
| 402 | `insufficient_minutes` | Nein | Du hast 0 nutzbare Minuten oder weniger, als die Transkription braucht, oder weniger als eine angefangene Minute einer Live-Sitzung. Ist die [automatische Aufladung](https://transcript1.com/de/docs/billing-and-limits#auto-top-up) aktiv, versucht transcript1 zuerst aufzuladen. Kaufe Minuten über `action_url` oder lass einen Agenten sie mit `POST /v1/topups` oder dem MCP-Tool `top_up` kaufen. |
| 402 | `no_active_plan` | Nein | Für die Minuten-Aufladung fehlt ein aktiver kostenpflichtiger Tarif. Diesen Fehler liefern `POST /v1/topups` und die Billing-Endpoints des Dashboards, nicht die Transkriptions-Endpoints. |
| 402 | `topup_needs_user` | Nur bei `pending` und `in_progress` | `POST /v1/topups` hat die Karte nicht belastet. `reason` nennt den Grund: `not_allowed` (die Zugangsdaten dürfen keine Aufladungen kaufen oder ihre Person ist kein Team-Admin), `cap_reached` (das monatliche Limit für Agenten reicht nicht mehr), `card_declined`, `authentication_required` oder `no_card`. Die Pakete lassen sich dann über `action_url` selbst kaufen. Bei `pending` (die Zahlung ist noch nicht bestätigt) und `in_progress` (eine andere Aufladung läuft) kann die Zahlung noch durchgehen: Versuche es später mit demselben `Idempotency-Key` erneut, statt zum Kauf über den Link aufzufordern. |
| 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 | `session_ended` | Nein | Die Live-Sitzung ist beendet, deshalb kann `POST /v1/live/sessions/:id/token` kein Token mehr ausstellen. Kommt auch als WebSocket-Event `error`. |
| 422 | `unsupported_language` | Nein | Die `language` der Live-Sitzung wird nicht unterstützt. |
| 422 | `unsupported_translation` | Nein | Die Zielsprache `translate_to` der Live-Sitzung wird nicht unterstützt, oder die Live-Übersetzung ist nicht verfügbar. |
| 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](https://transcript1.com/de/docs/uploads). |
| 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. |
| 429 | `too_many_live_sessions` | Ja | Die gleichzeitigen Live-Sitzungen deines Tarifs sind ausgeschöpft. Warte die in `Retry-After` angegebene Zahl von Sekunden (30). |
| 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. |
| 503 | `live_capacity` | Ja | Die gesamte Live-Kapazität ist belegt. Warte die in `Retry-After` angegebene Zahl von Sekunden (30) und lege die Sitzung erneut an. |
| 503 | `live_unavailable` | Nein | Die Live-Transkription ist gerade nicht verfügbar. |

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](https://transcript1.com/de/docs/billing-and-limits).

## Wann du einen Request wiederholen solltest

- Wiederhole den Request nur, wenn `retryable` auf `true` steht: bei `rate_limited`, `too_many_active_jobs`, `too_many_live_sessions`, `live_capacity`, `internal_error`, `service_unavailable` und bei `topup_needs_user` mit `reason` `pending` oder `in_progress`. 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` oder `POST /v1/topups` 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.

## Live-Transkription

`POST /v1/live/sessions` und die übrigen Live-Endpoints verwenden dieselbe Fehlerstruktur. Für sie gelten auch `invalid_request`, `unsupported_language`, `insufficient_minutes` und `email_not_verified` sowie die Live-Codes aus der Tabelle oben. Das Anlegen einer Sitzung ist nicht idempotent: Wiederholst du den Aufruf nach `too_many_live_sessions` oder `live_capacity`, entsteht eine neue Sitzung.

Sobald die Sitzung existiert, melden sich Probleme über den WebSocket als `error`-Events und Close-Codes, nicht als HTTP-Fehler. Alle Events stehen unter [Live-Transkription](https://transcript1.com/de/docs/live#websocket-protocol).

| Close-Code | Bedeutung |
|---|---|
| `1000` | Normales Schließen, nach `session.ended`. |
| `1011` | Unerwarteter Serverfehler. Setze die Sitzung mit einem neuen Token fort. |
| `1012` | Server-Neustart, nach `reconnect`. Setze die Sitzung mit einem neuen Token fort. |
| `4001` | Token ungültig, abgelaufen oder bereits verwendet. |
| `4004` | Sitzung nicht gefunden oder bereits beendet. |
| `4008` | Protokollverstoß: ein Audio-Frame mit ungerader Länge oder zu groß. |
| `4010` | Durch eine neuere Verbindung zur selben Sitzung ersetzt. |

Endet eine Live-Sitzung aus einem Grund wie `balance_exhausted` oder `idle_timeout`, ist das kein Fehler: Sie sendet `session.ended` mit einem Endgrund und wird gespeichert. Siehe [Endgründe](https://transcript1.com/de/docs/live#end-reasons).

## 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](https://transcript1.com/de/docs/webhooks) vom Typ `transcription.failed`. Scheitert eine Übersetzung, sendet transcript1 den Webhook `transcription.translation.failed`; die Transkription selbst scheitert dadurch nie.

| `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, und die automatische Aufladung konnte, falls aktiv, keine neuen hinzufügen. | Nach einer Aufladung. |
| `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.