Fehler behandeln

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:

Wenn die API den Request ablehnt

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, 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.

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.

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. Scheitert eine Übersetzung, sendet transcript1 den Webhook transcription.translation.failed; die Transkription selbst scheitert dadurch nie.

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