エラーとステータスコード

APIの問題レスポンスの読み方、失敗したリクエストの復旧方法、HTTPエラーと翻訳処理の失敗を区別する方法を説明します。

成功レスポンスをデコードする前に、HTTPステータスを確認してください。https://api.lingo.dev/v2のAPIは、失敗の詳細をJSON形式の問題レスポンスとして返します。ジョブを正常に取得できても、ジョブの処理自体は失敗している場合があるため、ジョブのステータスも確認してください。

問題レスポンスを読み解く #

問題レスポンスにはContent-Type: application/problem+jsonが使われます。共通のフィールドはtype、title、status、detailです。名前付きの問題には、影響を受けるリソースや対処方法を特定するフィールドも含まれます。

次の例は、ローカライズジョブが見つからない場合のレスポンスです。

json
{
  "type": "https://lingo.dev/docs/api/errors/localization-job-not-found",
  "title": "Localization job not found",
  "status": 404,
  "detail": "Localization job lfr_example not found.",
  "id": "lfr_example"
}

typeのURIは、問題を識別するものです。名前付きの各問題のフィールドとエンドポイントについては、APIエラーカタログを参照してください。エラーを保存または分類する際は、返されたURIを変更せずに保持してください。

無効なリクエストを修正する #

リクエストが検証に失敗すると、type: "about:blank"を含む400 不正なリクエストが返されます。検証の詳細が提供される場合は、errorsに各問題のpathとmessageが一覧表示されます。

json
{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "Request validation failed",
  "errors": [
    {
      "path": ["payload", "documents", 0, "source"],
      "message": "Expected a JSON object"
    }
  ]
}

パスは、payloadなどの検証対象となるリクエスト部分から始まり、その後にプロパティ名とゼロ始まりの配列インデックスが続きます。この例は、リクエスト本文の最初のdocumentsエントリにあるsourceを示しています。エンドポイントのスキーマに従って該当する値を修正してから、再送信してください。about:blankは汎用的な問題タイプのため、名前付きエラーカタログには記載されていません。

復旧方法を選ぶ #

HTTPステータス主な原因次の対応
400リクエストがルートのスキーマに一致していません。返された検証の詳細に従って、パス、クエリ、ヘッダー、または本文を修正してください。
401認証情報がないか、無効または有効期限切れになっています。使用するキーを読み込むか、ユーザーセッションを更新してください。
402クレジット不足、プランで利用できない機能、またはロールベースのアクセス制御で権限が引き下げられた後に無効化されたサービスキーが原因です。示された条件を確認し、アカウントまたはプランの要件を満たすように対応してください。
403権限や必須のユーザー識別情報の不足、または機能フラグによる制限が原因です。呼び出し元と、操作に必要なアクセス要件を確認してください。
404リソースが存在しないか、この呼び出し元からは参照できません。識別子、組織、リソースへのアクセス権限を確認してください。
409操作がリソースの状態と競合しています。リソースの現在の状態を取得してください。指示に従って、不足している成果物のアップロード、実行中の処理の完了、または終了したレビューの更新を行ってください。
413アップロードまたはリクエスト本文がサイズ上限を超えています。入力を減らすか、処理を分割してください。成果物のアップロードは1件あたり最大25 MiBです。
422リクエストの構造は有効ですが、操作の制約に違反しています。無効なレビュー編集や冪等性キーの再利用など、示された問題を修正してください。
429使用量または操作の上限に達しています。問題の詳細に再試行時刻が指定されている場合は、それに従ってください。指定がない場合は、アカウントの上限を確認してから再試行してください。
5xxサーバーまたは依存先がリクエストを完了できませんでした。リソースIDとリクエストIDを保持し、その操作の仕様で認められる場合にのみ再試行してください。

detailは、具体的な失敗の内容を示します。ステータスだけでは、失敗を十分に分類できません。プロキシやネットワーク障害によるレスポンスには、問題の詳細を示す本文が含まれない場合があります。秘密情報をログに記録しないよう注意しながら、診断用にHTTPステータスと読み取り可能なレスポンステキストを保持してください。

ローカライズの送信を再試行する #

作成リクエストを送信する前に、そのIdempotency-Keyを保存してください。レスポンスが失われた場合は、そのキーを使って同じ作成リクエストを再送信すると、元のジョブを取得できます。新しいキーを使うと、新しい処理が作成されます。

作成後はジョブIDを保存してください。別のジョブを作成するか判断する前に、そのジョブを取得して確認してください。アップロードには、SHA-256アドレスが示すものと完全に一致するバイト列を使用します。処理を開始する前に、未完了のアップロードをすべて完了してください。/startを繰り返しても、対象は同じジョブです。

受け入れ可否は開始時に確認されます。DailyTokenLimitReachedやクレジット不足が発生しても、ジョブは保留状態で残り、アカウントの問題が解決すれば後から開始できます。新しいジョブを繰り返し作成しても、アカウントの上限に関する問題は解決しません。

リクエストの失敗と処理の失敗を区別する #

GET /v2/localization/jobs/:idからHTTP 200が返された場合、ジョブの取得には成功しています。ただし、そのstatus._tagがFailedになっている場合もあります。status.message、各ターゲットのステータス、各段階の警告と失敗を確認してください。

別のターゲットが失敗しても、完了したターゲットは引き続きダウンロードできます。完了したものは保持し、原因を修正してから、再生成が必要な処理だけを送信してください。クライアント側のポーリングがタイムアウトしても、ジョブはキャンセルされません。

プロビジョニングには、専用の種類別の結果と復旧方法があります。レビューでの判断には、専用の終了済みレビューと無効な編集に関するエラーがあります。失敗するたびに元の書き込みを繰り返すのではなく、それぞれのリソースの状態に基づいて復旧してください。