Fouten afhandelen

Een request kan meteen worden geweigerd. Een transcriptie kan ook pas later mislukken, nadat de API die al heeft geaccepteerd. In dat geval staat status op failed. Houd deze twee situaties uit elkaar bij het afhandelen van fouten.

Zo ziet een foutresponse eruit

Als een /v1-request mislukt, krijg je dit vaste formaat:

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

Laat je code reageren op code, niet op de tekst van message. Die tekst is voor de gebruiker en kan veranderen. Staat retryable op true, dan kan hetzelfde request later wel slagen.

Afhankelijk van de fout krijg je naast retryable extra velden:

Wanneer de API je request weigert

Bij browserrequests met een inlogcookie controleren we ook vanaf welke site het request komt. Een andere site krijgt 403 forbidden_origin. Voor API-requests met een bearer-token in de Authorization-header geldt die controle niet.

In elke 429-response staat Retry-After: het aantal seconden dat je moet wachten. De limieten zelf vind je bij Minuten, abonnementen en limieten.

Wanneer stuur je een request opnieuw?

• Herhaal alleen requests met retryable op true: rate_limited, too_many_active_jobs, too_many_live_sessions, live_capacity, internal_error, service_unavailable en topup_needs_user met reason pending of in_progress. Houd de wachttijd uit Retry-After aan. Ontbreekt die header, wacht dan bij elke poging langer.
• Herhaal je POST /v1/transcriptions of POST /v1/topups, gebruik dan dezelfde Idempotency-Key-header. Zo betaal je niet dubbel als het eerste request toch is gelukt.
• Pas bij alle andere codes eerst je request aan voordat je het nog eens verstuurt.

Live transcriptie

POST /v1/live/sessions en de andere live endpoints gebruiken dezelfde foutenvelop. invalid_request, unsupported_language, insufficient_minutes en email_not_verified gelden er ook voor, samen met de live codes in de tabel hierboven. Een sessie aanmaken is niet idempotent: een nieuwe poging na too_many_live_sessions of live_capacity maakt dus een nieuwe sessie aan.

Zodra de sessie bestaat, komen problemen binnen op de WebSocket als error-events en sluitcodes, niet als HTTP-fouten. Zie Live transcriptie voor elk event.

Een live sessie die eindigt om een reden als balance_exhausted of idle_timeout is geen fout: hij stuurt session.ended met een eindreden en wordt opgeslagen. Zie Eindredenen.

Als een transcriptie later mislukt

Ook na een geslaagd request kan de transcriptie nog mislukken. Dan krijg je status op failed en error: { "code", "message" } in het object. Controleer error dus ook tijdens het pollen of bij een webhook van het type transcription.failed. Mislukt een vertaling, dan wordt de webhook transcription.translation.failed verstuurd en mislukt het transcript daardoor nooit.

Mislukt een transcriptie of annuleer je die, dan betaal je niets. Hadden we al minuten afgeschreven, dan krijg je die terug.