エラーコードと対処方法

エラーには、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、internal_error、service_unavailableです。Retry-Afterがあれば指定どおりに待ち、なければ再送の間隔を徐々に延ばしてください。
• 文字起こしの作成（POST /v1/transcriptions）を再試行するときは、同じIdempotency-Keyヘッダーを使ってください。元のリクエストがすでに成功していても、二重課金を防げます。
• それ以外のコードでは、原因を解消してからリクエストを送り直してください。

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

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

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