# ジョブとエラー

IMG2Excel API のジョブ状態、XLSX のダウンロード、エラーコード、レート制限、再試行と結果の保持期間を解説します。

公式ドキュメント: https://img2excel.net/ja/docs/api/jobs

`GET /api/v1/jobs/{job_id}`

同期エンドポイントは変換結果を直接返します。このジョブ取得エンドポイントは、非同期処理、冪等キーによる再試行で返された実行中ジョブの状態確認、保持期間内のダウンロード URL の更新に使用します。同期変換の失敗時は `422` とジョブのレスポンスが返されます。既存ジョブの取得時は `200` が返されるため、必ず `status` を確認してください。

変換ジョブの現在の状態を取得します。画像から Excel と手書きから Excel は、このエンドポイントを共通で使用します。

## リクエスト

| パラメーター | 場所 | 必須 | 説明 |
| --- | --- | --- | --- |
| `job_id` | パス | はい | ジョブ作成時に返された `id`。 |
| `Authorization` | ヘッダー | はい | `Bearer $IMG2EXCEL_API_KEY`。ジョブを作成したアカウントのキーを使用します。 |

```bash
curl --fail-with-body https://img2excel.net/api/v1/jobs/job_0123456789abcdef0123456789abcdef \
  -H "Authorization: Bearer $IMG2EXCEL_API_KEY"
```

有効なリクエストには **200 OK** が返ります。変換自体が失敗していても同様です。必ず JSON の `status` を確認してください。HTTP リクエストの成功は、ブックの完成を意味しません。

## ジョブの状態

| 状態 | 意味 | 次の操作 |
| --- | --- | --- |
| `queued` | アップロードが受理され、実行待ちです。 | 2〜3 秒後に再確認。 |
| `processing` | 変換中です。 | 2〜3 秒後に再確認。 |
| `succeeded` | ブックが完成しました。 | `result.download_url` からファイルをダウンロードし、ポーリングを停止。 |
| `failed` | 変換を完了できませんでした。 | `error.code` と `error.message` を読み、ポーリングを停止。 |
| `expired` | 結果の保持期間が終了しました。 | ポーリングを停止。必要に応じて、新しい冪等キーでジョブを作成。 |

## レスポンス

### 変換成功

```json
{
  "id": "job_0123456789abcdef0123456789abcdef",
  "type": "image-to-excel",
  "status": "succeeded",
  "credits_reserved": 1,
  "credits_used": 1,
  "created_at": "2026-09-07T12:00:00.000Z",
  "completed_at": "2026-09-07T12:00:18.000Z",
  "result": {
    "filename": "table_result.xlsx",
    "content_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
    "size_bytes": 17330,
    "download_url": "https://signed-storage-url.example/...",
    "download_url_expires_in": 900
  }
}

```

上記のダウンロード URL は例です。自分のジョブが返した URL を使用してください。

| フィールド | 型 | 説明 |
| --- | --- | --- |
| `id` | 文字列 | ジョブ識別子。 |
| `type` | 文字列 | `image-to-excel` または `handwriting-to-excel`。 |
| `status` | 文字列 | 上記の 5 つの状態のいずれか。 |
| `credits_reserved` | 整数 | 変換に必要なクレジット数。 |
| `credits_used` | 整数 | 変換で消費したクレジット数。 |
| `created_at` | 文字列 | ISO 8601 形式の UTC 時刻。 |
| `completed_at` | 文字列または null | 完了時刻。完了前は `null`。 |
| `result` | オブジェクト | 成功し、結果が利用可能な場合に含まれます。 |
| `error` | オブジェクト | 変換失敗時に含まれます。`code` と `message` を持ちます。 |

### 結果のフィールド

| フィールド | 型 | 説明 |
| --- | --- | --- |
| `filename` | 文字列 | 推奨されるブックのファイル名。 |
| `content_type` | 文字列 | XLSX の MIME タイプ。 |
| `size_bytes` | 整数または null | ファイルサイズ（バイト）。取得できない場合は `null`。 |
| `download_url` | 文字列 | 一時的な署名付きダウンロード URL。 |
| `download_url_expires_in` | 整数 | URL の有効秒数：`900`（15 分）。 |

結果は完了後 24 時間保持されます。その期間中に URL が期限切れになった場合は、ジョブを再取得して新しい URL を取得します。署名付き URL をログに記録したり、公開したりしないでください。

### 変換失敗

変換が失敗した場合、ジョブ取得時のレスポンスに `error` が含まれます。例：

```json
{
  "id": "job_0123456789abcdef0123456789abcdef",
  "type": "image-to-excel",
  "status": "failed",
  "credits_reserved": 1,
  "credits_used": 0,
  "created_at": "2026-10-04T09:00:00.000Z",
  "completed_at": "2026-10-04T09:00:18.000Z",
  "error": {
    "code": "CONVERSION_FAILED",
    "message": "The conversion could not be completed."
  }
}
```

変換失敗時にクレジットは消費されません。再試行の前に返されたメッセージを確認してください。新しい変換には新しい冪等キーが必要です。以前のキーを再利用すると、同じ失敗したジョブが返ります。

## ポーリングとダウンロード

`pip install requests` で `requests` をインストールし、`IMG2EXCEL_API_KEY` を設定します。`job_id` を自分のジョブ ID に置き換えてください。この例では状態確認を最大 60 回行います。ネットワークや HTTP エラーが発生するとスクリプトは停止します。本番環境では、下記の再試行の指針に従って一時的な障害を処理してください。

```python
import os
import time
import requests

job_id = "job_0123456789abcdef0123456789abcdef"
headers = {"Authorization": f"Bearer {os.environ['IMG2EXCEL_API_KEY']}"}

for _ in range(60):
    response = requests.get(
        f"https://img2excel.net/api/v1/jobs/{job_id}",
        headers=headers,
        timeout=30,
    )
    response.raise_for_status()
    job = response.json()

    if job["status"] == "succeeded":
        xlsx = requests.get(job["result"]["download_url"], timeout=60)
        xlsx.raise_for_status()
        with open(job["result"]["filename"], "wb") as output:
            output.write(xlsx.content)
        break
    if job["status"] in ("failed", "expired"):
        raise RuntimeError(job.get("error", {"code": job["status"]}))

    time.sleep(2)
else:
    raise TimeoutError("IMG2Excel conversion did not finish in time")

```

## リクエストエラー

HTTP リクエストが拒否されると、2xx 以外のステータスとエラーオブジェクトが返ります。

```json
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "A valid API key is required."
  }
}
```

| HTTP ステータス | コード | 原因 | 対処方法 |
| --- | --- | --- | --- |
| 400 | `INVALID_REQUEST` | リクエストボディを multipart/form-data として解析できません。 | HTTP クライアントの multipart アップロード機能を使用。 |
| 400 | `INVALID_FILE` | `file` がないか、ファイルではありません。 | `file` フィールドに画像を添付。 |
| 400 | `INVALID_IDEMPOTENCY_KEY` | キーが 200 文字を超えています。 | ヘッダー値を短くする。 |
| 401 | `INVALID_API_KEY` | キーが未指定、無効、期限切れ、失効済み、または必要な変換権限がありません。 | `Authorization: Bearer ...` リクエストヘッダーと [API 設定](https://img2excel.net/ja/settings/api) のキーを確認。 |
| 403 | `API_ACCESS_REQUIRED` | API の利用権限がありません。 | Business または プロフェッショナル クレジットパッケージを購入。 |
| 404 | `JOB_NOT_FOUND` | ジョブが存在しないか、別のアカウントのものです。 | ID と、作成元アカウントのキーを確認。 |
| 409 | `JOB_CONFLICT` | 競合によりジョブを作成できませんでした。 | 元の冪等キーで再試行し、既存ジョブを取得。 |
| 413 | `FILE_TOO_LARGE` | ファイルが 4MB を超えています。 | 画像を小さくして再送信。 |
| 429 | `RATE_LIMITED` | 直近 1 分間のジョブ作成数が多すぎます。 | `Retry-After` の時間を待ち、同じ冪等キーで再試行。 |
| 429 | `CONCURRENCY_LIMITED` | 待機中または実行中のジョブが多すぎます。 | 既存ジョブの完了を待ってから送信。 |

クレジット不足や認識の失敗は、ジョブが受理された**後**に発生することがあります。その場合、アップロードリクエストは成功していても、ジョブ取得時に `status: "failed"`、`error.code`、`error.message` で報告されます。クレジット不足のメッセージがある場合は残高を確認してください。

## 制限と再試行

| 制限 | 値 |
| --- | --- |
| アカウントごとの新規ジョブ | 1 分間に 30 件、両変換エンドポイントで共有 |
| 待機中または実行中の同時ジョブ | Business：3 件、プロフェッショナル：10 件 |
| ファイルサイズ | 最大 4MB |
| ダウンロード URL の有効期間 | 15 分 |
| 結果の保持期間 | 変換成功から 24 時間 |

`429` が返された場合は、`Retry-After` レスポンスヘッダーで指定された時間だけ待ってから再試行してください。一時的な `5xx` エラーやネットワーク障害では、待機時間を段階的に延ばす指数バックオフにランダムな遅延を加えて再試行します。アップロードの再試行には元の冪等キーを、状態確認の再試行には同じジョブ ID を使用してください。アプリケーションにはポーリング全体の期限を設定します。

無効なリクエストや認証エラーは自動再試行せず、先にリクエストを修正してください。問題が続く場合は、API キーやダウンロード URL を含めずに、ジョブ ID とエラーコードを [サポート](mailto:support@img2excel.net) に送ってください。

---

OpenAPI 3.1: https://img2excel.net/api/openapi.json
API ドキュメント全文: https://img2excel.net/ja/docs/api/text/llms-full.txt