エラーコードと対処方法

エラーには、APIがリクエストを受け付けなかった場合と、受け付けた後で文字起こしに失敗した場合があります。後者では、文字起こしのstatusがfailedになります。リクエストが通っただけでは、文字起こしの成功は確定しません。

エラーレスポンスの形式

/v1へのリクエストでエラーが起きると、次の形式のJSONを返します。

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

処理の分岐にはcodeを使い、messageはユーザーへの表示用として扱ってください。messageの文言は変更することがあります。retryableがtrueなら、時間を置いて同じリクエストを再送すると成功する可能性があります。

エラーの種類によっては、retryableと並んで次のフィールドも返します。

リクエスト時に返るエラー

Bearer認証ではなくログインCookieを使うブラウザーのリクエストは、送信元のオリジンも検証します。別サイトから送ると403 forbidden_originを返します。Authorizationヘッダーを付けたAPIリクエストは、この検証の対象外です。

429では必ずRetry-Afterヘッダーを返します。値は、次のリクエストまで待つ秒数です。各上限の値は料金と制限で確認してください。

自動再試行の判断基準

• retryableがtrueのときだけ再送します。対象はrate_limited、too_many_active_jobs、too_many_live_sessions、live_capacity、internal_error、service_unavailableと、reasonがpendingまたはin_progressのtopup_needs_userです。Retry-Afterがあれば指定どおりに待ち、なければ再送の間隔を徐々に延ばしてください。
• POST /v1/transcriptionsやPOST /v1/topupsを再試行するときは、同じIdempotency-Keyヘッダーを使ってください。元のリクエストがすでに成功していても、二重課金を防げます。
• それ以外のコードでは、原因を解消してからリクエストを送り直してください。

ライブ文字起こし

POST /v1/live/sessionsなどのライブ用エンドポイントも、同じエラーレスポンスの形式を使います。上の表のライブ用コードに加えて、invalid_request、unsupported_language、insufficient_minutes、email_not_verifiedも該当します。セッションの作成は冪等ではないため、too_many_live_sessionsやlive_capacityのあとに再送すると、新しいセッションが作られます。

セッションができたあとの問題は、HTTPエラーではなく、WebSocketのerrorイベントとクローズコードで届きます。すべてのイベントはライブ文字起こしを参照してください。

balance_exhaustedやidle_timeoutなどの理由で終了したライブセッションはエラーではありません。終了理由つきのsession.endedが送られ、セッションは保存されます。終了理由を参照してください。

受け付け後に文字起こしが失敗した場合

statusがfailedになったら、文字起こしオブジェクトのerror: { "code", "message" }を確認してください。APIがリクエストへのレスポンスを返した後に、処理が失敗することもあります。ポーリングのレスポンス、またはtranscription.failedのWebhookでerrorを確認します。 翻訳が失敗した場合はtranscription.translation.failedのWebhookを送り、文字起こし自体が失敗になることはありません。

文字起こしに失敗した場合やキャンセルした場合は課金しません。すでに差し引いた分数があれば、失敗・キャンセル時に元に戻します。