エラーコード

リクエストが失敗すると、APIはマシンリーダブルな code と人間が読める message を含むJSONエラーレスポンスを返します：

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description of the error"
  }
}

code フィールドは安定しており、アプリケーションロジックで安全にマッチングに使用できます。message フィールドは時間とともに変わる可能性があり、ログやデバッグ用です。

エラーコードリファレンス

コード	HTTPステータス	説明	リトライ可能	解決方法
UNAUTHORIZED	401	認証トークンが欠落、無効、または期限切れ	いいえ	APIキーが有効で期限切れでないことを確認
KEY_EXPIRED	401	APIキーの有効期限が過ぎている	いいえ	ダッシュボードまたはAPIから新しいAPIキーを作成
FORBIDDEN	403	認証済みだが、このリソースへのアクセス権限がない	いいえ	自分のリソースのみアクセス可能
NOT_FOUND	404	リクエストされたリソースが存在しない	いいえ	リソースIDが正しいことを確認
VALIDATION_ERROR	400	リクエストボディがスキーマバリデーションに失敗	いいえ	必須フィールドとデータ型がスキーマに一致していることを確認
INVALID_MIME_TYPE	400	アップロードされたファイルのMIMEタイプがサポートされていない	いいえ	サポートされているファイルタイプ（PDFまたはDOCX）を使用
FILE_TOO_LARGE	400	アップロードされたファイルが10 MBのサイズ制限を超えている	いいえ	ファイルサイズを削減するか、小さなドキュメントに分割
MAX_KEYS_REACHED	400	アクティブなAPIキーの上限10個に達した	いいえ	新しいキーを作成する前に未使用のキーを無効化
USAGE_LIMIT_EXCEEDED	429	月間抽出制限に達した	いいえ	プランをアップグレードするか、次の請求期間まで待つ
INTERNAL_ERROR	500	予期しないサーバーエラー	はい	指数バックオフでリトライ。持続する場合はサポートに連絡
NOT_CONFIGURED	501	必要なサーバー側サービスが設定されていない	いいえ	サポートに連絡 -- サーバー設定の問題を示します
EXTRACTION_FAILED	502	AI抽出処理が失敗	はい	リトライ -- 一時的な問題の可能性があります。PDFが有効で読み取れることを確認
EXTRACTION_PARSE_ERROR	502	AIがJSONとして解析できないレスポンスを返した	はい	リトライ -- 次回のリクエストでAIが有効な出力を生成する可能性があります

リトライ可能なエラー

以下のエラーコードのみリトライすべきです：

• INTERNAL_ERROR -- サーバー側の予期しない障害。
• EXTRACTION_FAILED -- AI抽出プロセスが失敗、多くの場合一時的な問題が原因。
• EXTRACTION_PARSE_ERROR -- AIが解析できない不正な出力を返した。

リトライする場合は、1秒から始まる指数バックオフを使用し、最大3回のリトライを行います：

試行	遅延
1回目のリトライ	1秒
2回目のリトライ	2秒
3回目のリトライ	4秒

3回のリトライ後もリクエストが失敗する場合は、エラーをログに記録し、ユーザーまたは監視システムに通知してください。

リトライロジックの実装に関する完全なガイドについては、エラーハンドリングをご覧ください。

HTTPステータスコードの概要

ステータス	意味
200	成功 -- リクエストが正常に完了しました
400	不正なリクエスト -- バリデーションエラー、無効なファイルタイプ、ファイルサイズ超過、またはキー制限に到達
401	未認証 -- 認証に失敗（トークンが欠落、無効、または期限切れ）
403	禁止 -- 認証済みだが、リクエストされたリソースへの権限がない
404	未検出 -- リクエストされたリソースが存在しない
429	リクエスト過多 -- 月間抽出使用量の制限を超過
500	内部サーバーエラー -- サーバー側の予期しない障害
501	未実装 -- 必要なサーバー側サービスが設定されていない
502	不正なゲートウェイ -- AI抽出または解析が失敗