ガイド

エラーハンドリング

失敗したv1リクエスト（2xx以外のレスポンス）はすべて、以下に示す同一のJSON構造を返します。このページは、各エラーのdoc_urlがリンクする先でもあります。各コードには固有のアンカーセクションがあるため、実際のエラーレスポンスからdoc_urlをたどると、該当コードの説明に直接移動します。

エラーの構造

{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_parameter",
    "message": "A required parameter is missing.",
    "doc_url": "https://imagetotable.ai/developers/guides/errors#missing_parameter",
    "param": "file"
  }
}
  • type — このエラーが属する大まかなカテゴリです（下記の表を参照）。個々のcodeをすべてチェックしなくても、エラーハンドリングコードで大まかな分岐（「認証の問題か、バリデーションの問題か」）を行うのに役立ちます。
  • code — 特定の安定したエラー識別子です。コード内でマッチングに使用するもので、後でmessageの文言が改善されても変更されることはありません。
  • message — 人間が読める説明です。ログやデバッグに役立ちますが、解析を目的としたものではありません。
  • doc_url — このページの該当codeのセクションへの直接リンクです。
  • param — バリデーションエラー（missing_parameter、invalid_parameter、duplicate_field_name）の場合にのみ存在し、エラーの原因となったリクエストフィールドを指定します。該当しない場合は、nullではなく、フィールド自体が省略されます。

エラータイプ

各 code は、1つの type にのみ属します。

タイプ意味
authentication_errorリクエストの認証方法（または認証の有無）に問題があります。
invalid_request_errorリクエスト自体が不正です（パラメータの欠落または無効）。
not_found_errorURLで指定されたリソース（ドキュメント、バッチ、テンプレートID）が存在しないか、アカウントに属していません。
insufficient_creditsアカウントに、リクエストされた（有料）アクションを実行するための十分なクレジットがありません。
rate_limit_errorこのエンドポイントカテゴリのリクエストレートを超えました。詳細はレート制限をご覧ください。
internal_errorサーバー側で問題が発生しました（お客様側の問題ではありません）。

特別なケース: processing_error

processing_error は、トップレベルの {"error": ...} レスポンスで見られる type ではありません。これ自体がAPIコールを失敗させることは決してありません。代わりに、バッチ内で抽出できなかった単一のドキュメントを説明するものです。正常に処理された同じバッチ内の他のドキュメントと共に、ステータス200 OKの GET /batches/{batch_name}/results レスポンス内で、そのドキュメントに "status": "failed" として反映されているのを確認できます。成功したAPIコール内のドキュメントレベルの失敗を、バッチ全体を再試行すべきエラーとして扱わないでください。各ドキュメントの個別の status を確認してください。

エラーコード

missing_api_key

タイプ: authentication_error · HTTPステータス: 401

APIキーが提供されていません。Authorization: Bearer <key> として送信してください。

invalid_api_key

タイプ: authentication_error · HTTPステータス: 401

提供されたAPIキーが無効か、そのアカウントが無効になっています。

plan_required

タイプ: authentication_error · HTTPステータス: 403

FreeプランではこのAPIは利用できません。Basic以上にアップグレードしてください。

missing_parameter

タイプ: invalid_request_error · HTTPステータス: 400

必須パラメータが不足しています。エラーオブジェクトの param で該当パラメータを確認してください。

invalid_parameter

タイプ: invalid_request_error · HTTPステータス: 400

パラメータの値が無効です。詳細は param と message を確認してください。このコードは、不正な crop 文字列、範囲外の limit、処理対象がないバッチなど、さまざまなケースをカバーする汎用コードです。

duplicate_field_name

タイプ: invalid_request_error · HTTPステータス: 400

このテンプレートに同じ名前のフィールドがすでに存在します。フィールド名はテンプレート内で一意である必要があります。

idempotency_key_reused

タイプ: invalid_request_error · HTTPステータス: 400

この Idempotency-Key は、異なるパラメータのリクエストですでに使用されています。本当に異なるリクエストには新しいキーを使用してください。詳細な動作は冪等性を参照してください。

document_not_found

タイプ: not_found_error · HTTPステータス: 404

指定されたIDのドキュメントが見つかりませんでした（存在しないか、アカウントに属していません）。

batch_not_found

タイプ: not_found_error · HTTPステータス: 404

指定された名前のバッチが見つかりませんでした。

template_not_found

タイプ: not_found_error · HTTPステータス: 404

指定されたIDのテンプレートが見つかりませんでした。

insufficient_credits

タイプ: insufficient_credits · HTTPステータス: 402

この操作を実行するためのクレジットが不足しています。再試行する前に、GET /account で現在の available_credits を確認してください。

rate_limit_exceeded

タイプ: rate_limit_error · HTTPステータス: 429

リクエストが多すぎます。速度を落とし、ウィンドウがリセットされた後に再試行してください。X-RateLimit-Reset レスポンスヘッダーとレート制限ガイドを参照してください。

internal_error

タイプ: internal_error · HTTPステータス: 500

予期しないエラーが発生しました。これが続く場合は、お客様ではなく当社側の問題です。再現可能であれば、お問い合わせの際にその情報を含めていただくと役立ちます。

📮 contact email: [email protected]