エラーと再試行

共通ガイドは画像からテキストと画像から表に適用されます。入力、形式、固有のエラーは各 API リファレンスをご確認ください。

エラー応答

JSON エラー応答の例：

{
  "request_id": "b2c8ec98-2a36-4f87-99d2-3d7839b92518",
  "error": {
    "code": "insufficient_balance",
    "message": "Recognition did not complete",
    "required_reservation_usd": "0.011288000"
  }
}

HTTP ステータスコード

HTTP	error.code
400	invalid_request, invalid_idempotency_key, invalid_image
401	unauthorized
402	insufficient_balance
403	account_unavailable
405	invalid_request
409	idempotency_conflict, request_in_progress
413	image_too_large, input_limit_exceeded
415	unsupported_media_type
422	recognition_blocked
429	rate_limit_exceeded, concurrency_limit_exceeded
502	recognition_failed, output_truncated, empty_result, invalid_usage
503	service_unavailable, settlement_pending, export_failed
504	request_timeout

HTTP	原因	対応
400 / 413 / 415	不正なリクエスト、画像サイズ、形式	アップロードを修正または縮小する
405	HTTP メソッド違い	POST を使用する
401	API キーが無効または不足	Bearer キーを確認する
403	アカウントを利用できない	メール確認やアカウント制限を解決する
402	残高不足	入金し error.required_reservation_usd を確認する。残高と一時確保も参照する
409	冪等 ID の競合、または処理中	request_in_progress なら同じ ID と画像で待って再試行する。競合なら操作 ID を修正する
429	頻度または同時実行の上限	Retry-After に従って待つ
422 / 確定した 502	確定した認識失敗	認識料金は発生しない。原因を確認する
503 / 504 / 状態不明	サービス、精算、処理時間の不確実性	無料と決めつけず同じ Idempotency-Key と元画像で再試行する

エラーは request_id、error.code、error.message を含む JSON です。すべての応答に Cache-Control: no-store が付きます。認識のストリーミングには対応せず、成功時は選択した形式、エラー時は JSON で返します。サポートには X-Request-Id を保存してください。

Idempotency-Key は操作 ID です。16～128文字の ASCII 英数字または . _ : - を使います。新しい画像には新しい一意な ID、再試行には同じ ID・元の画像バイト・MIME を使用します。キーを変更してもアカウント単位で共有されます。受理後24時間以内の完了済み操作は元の request_id・結果・料金を Idempotency-Replayed: true と共に返し、再生成・再課金しません。

新しい操作や別のエンドポイントには異なる Idempotency-Key を使います。テキスト API と表 API で同じ値を使うと 409 idempotency_conflict になります。同じ操作の形式変更では元のキーと画像を再利用します。

再試行の手順

通信エラー、request_in_progress、settlement_pending では同じ ID と画像を保ち、Retry-After 秒待って再試行してください。精算未確定中は新規操作を作らないでください。保存済みの終端エラーは同じエラーを返します。失敗を確認し意図的に再実行するときだけ新 ID を使います。24時間後は同 ID でも新規課金される可能性があります。未復旧の操作は引き続き再利用できません。

課金の安全性

確定した認識失敗は課金されません。一方、応答の消失や settlement_pending は精算済み、または残高確保中の可能性があります。結果が未確定の間は新しい Idempotency-Key で別操作を開始せず、元の ID と画像で確認し、問い合わせ時は X-Request-Id を記録してください。

エラー応答

HTTP ステータスコード

冪等性

再試行の手順

課金の安全性