生成状態の取得

GET /file/status/{requestId} エンドポイントは、PDF 生成リクエストの状態（queued / processing / completed / failed）を返します。非同期生成の完了待ちや失敗理由の確認に使います。完了していれば各ファイルのダウンロードパスが、失敗していればエラーコードと理由が含まれるので、ダウンロード API を繰り返し呼んで完了を推測する必要はありません。

エンドポイント情報

• URL: https://api.re-port-flow.com/v1/file/status/{requestId}
• メソッド: GET
• 認証: 他のエンドポイントと同じ（appkey ヘッダー、または Authorization: Bearer <アクセストークン>）
• Rate Limit: 300 req/min（Workspace単位。ダウンロード API の 100 req/min とは別枠）

パラメータ

パラメータ	型	必須	説明
requestId	string	✓	生成 API のレスポンスの requestId（16文字の英数字。パスパラメータ）

使用例

cURL

curl -i https://api.re-port-flow.com/v1/file/status/kZ3mP9qL2xV7nR4t \
  -H "appkey: your-application-key"

JavaScript

async function waitForCompletion(requestId, { timeoutMs = 300000 } = {}) {
  const deadline = Date.now() + timeoutMs;
  let notFoundRetries = 0;

  for (;;) {
    // 期限は 1 回の待ちとリクエストにも適用する（axios の timeout: 0 は「無制限」）
    const remainingMs = deadline - Date.now();
    if (remainingMs <= 0) break;

    let res;
    try {
      res = await axios.get(
        `https://api.re-port-flow.com/v1/file/status/${requestId}`,
        { headers: { 'appkey': process.env.APP_KEY }, timeout: remainingMs }
      );
    } catch (e) {
      // 生成直後の 404 は、ジョブの記録を保存できなかった生成中のリクエストのことがある。2 回まで確かめ直す
      if (e.response?.status === 404 && notFoundRetries < 2) {
        notFoundRetries += 1;
        await new Promise(resolve => setTimeout(resolve, Math.min(3000, Math.max(0, deadline - Date.now()))));
        continue;
      }
      // 429（状態 API は 300 req/min）は Retry-After 秒待って確かめ直す
      if (e.response?.status === 429) {
        const waitMs = Number(e.response.headers['retry-after'] ?? 60) * 1000;
        await new Promise(resolve => setTimeout(resolve, Math.min(waitMs, Math.max(0, deadline - Date.now()))));
        continue;
      }
      throw e;
    }

    if (res.data.status === 'completed') return res.data;
    if (res.data.status === 'failed') {
      throw new Error(`${res.data.error.code}: ${res.data.error.message}`);
    }

    // queued / processing のあいだは Retry-After（秒）が付く
    const waitMs = Number(res.headers['retry-after'] ?? 2) * 1000;
    await new Promise(resolve => setTimeout(resolve, Math.min(waitMs, Math.max(0, deadline - Date.now()))));
  }

  throw new Error(`タイムアウトしました: ${requestId}`);
}

Python

import os
import time
import requests

def wait_for_completion(request_id, timeout_sec=300):
    deadline = time.time() + timeout_sec
    not_found_retries = 0
    while True:
        # 期限はリクエストと待ちにも適用する（timeout 無しの requests は無期限に待つ）
        remaining = deadline - time.time()
        if remaining <= 0:
            break
        res = requests.get(
            f"https://api.re-port-flow.com/v1/file/status/{request_id}",
            headers={'appkey': os.getenv('APP_KEY')},
            timeout=remaining,
        )
        # 生成直後の 404 は、ジョブの記録を保存できなかった生成中のリクエストのことがある。2 回まで確かめ直す
        if res.status_code == 404 and not_found_retries < 2:
            not_found_retries += 1
            time.sleep(min(3, max(0, deadline - time.time())))
            continue
        # 429（状態 API は 300 req/min）は Retry-After 秒待って確かめ直す
        if res.status_code == 429:
            time.sleep(min(int(res.headers.get('Retry-After', '60')), max(0, deadline - time.time())))
            continue
        res.raise_for_status()
        body = res.json()

        if body['status'] == 'completed':
            return body
        if body['status'] == 'failed':
            raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")

        # queued / processing のあいだは Retry-After（秒）が付く
        time.sleep(min(int(res.headers.get('Retry-After', '2')), max(0, deadline - time.time())))

    raise TimeoutError(request_id)

レスポンス

生成中 (200 OK)

HTTP/1.1 200 OK
Retry-After: 2
Content-Type: application/json

{
  "requestId": "kZ3mP9qL2xV7nR4t",
  "status": "processing",
  "designId": "0eUDdgAjNXrrItA2",
  "version": 3,
  "files": [],
  "createdAt": "2026-10-01T00:00:00.000Z"
}

queued / processing のあいだは Retry-After: 2 ヘッダーが付きます。この秒数をポーリング間隔に使ってください。

完了 (200 OK)

{
  "requestId": "kZ3mP9qL2xV7nR4t",
  "status": "completed",
  "designId": "0eUDdgAjNXrrItA2",
  "version": 3,
  "files": [
    {
      "fileId": "Hn4sT8wQ1cV6bX2e",
      "fileName": "invoice.pdf",
      "pageCount": 1,
      "downloadPath": "/v1/file/download/kZ3mP9qL2xV7nR4t/Hn4sT8wQ1cV6bX2e"
    }
  ],
  "createdAt": "2026-10-01T00:00:00.000Z",
  "completedAt": "2026-10-01T00:00:05.000Z"
}

downloadPath は API のホスト（https://api.re-port-flow.com）からの相対パスで、/v1 を含みます。ベース URL（https://api.re-port-flow.com/v1）に連結すると /v1/v1/... になるので、ホストに連結してください。認証ヘッダーを付けて GET すると PDF を取得できます（PDF のダウンロード）。

複数生成で一部のファイルだけが失敗した場合も status は completed で、失敗したファイルが failedFiles に入ります（fileId は 202 応答で返した ID です）。

{
  "requestId": "kZ3mP9qL2xV7nR4t",
  "status": "completed",
  "files": [
    { "fileId": "Hn4sT8wQ1cV6bX2e", "fileName": "invoice_001.pdf", "pageCount": 1, "downloadPath": "/v1/file/download/kZ3mP9qL2xV7nR4t/Hn4sT8wQ1cV6bX2e" }
  ],
  "failedFiles": [
    { "fileId": "Rt7uY2iO9pA4sD6f", "fileName": "invoice_002.pdf", "code": "INTERNAL_ERROR", "message": "PDF generation failed due to an internal error." }
  ],
  "...": "..."
}

失敗 (200 OK)

{
  "requestId": "kZ3mP9qL2xV7nR4t",
  "status": "failed",
  "designId": "0eUDdgAjNXrrItA2",
  "version": 3,
  "files": [],
  "failedFiles": [
    {
      "fileId": "Hn4sT8wQ1cV6bX2e",
      "fileName": "invoice.pdf",
      "code": "PARAMS_TYPE_MISMATCH",
      "message": "Parameter validation failed: \"amount\" must be a number"
    }
  ],
  "error": {
    "code": "PARAMS_TYPE_MISMATCH",
    "message": "Parameter validation failed: \"amount\" must be a number"
  },
  "createdAt": "2026-10-01T00:00:00.000Z",
  "completedAt": "2026-10-01T00:00:01.000Z"
}

error.code には、エラーコード一覧 のコード（例: PARAMS_TYPE_MISMATCH、FILE_GENERATION_FAILED、INTERNAL_ERROR、GENERATION_INTERRUPTED）が入ります。error.message は英語です。月間ページ数の上限（PLAN_PAGE_LIMIT_EXCEEDED）は受付前に判定され、生成 API が 403 を返すため、ここには現れません。

非同期生成が失敗したときは、ファイルごとの理由が failedFiles にも入ります（単一生成は 1 件。複数生成ですべて失敗した場合は、ファイルごとに理由が異なることがあり、error.code は FILE_GENERATION_FAILED）。

レスポンスフィールド

フィールド	型	説明
requestId	string	リクエストID
status	string	queued / processing / completed / failed
designId	string	テンプレート ID
version	integer	テンプレートのバージョン
files	array	完了したファイル（fileId / fileName / pageCount / downloadPath）。完了前は空配列
failedFiles	array	失敗したファイルごとの理由（fileId / fileName / code / message。fileId は記録が無い場合に省略）。複数生成の部分成功（completed）と、非同期生成の失敗（failed）で返る。失敗が無ければ含まれない
error	object	status が failed のときの理由（code / message）
createdAt	string	受付日時（ISO 8601）
completedAt	string	完了・失敗日時（ISO 8601）。completed / failed のときだけ

queued について

queued は予約済みの値です。現在の実装では受付後すぐに生成を始めるため、通常は processing / completed / failed のいずれかが返ります。

状態の保持期間

• 非同期生成の状態（ジョブの記録）は、完了・失敗から 24 時間保持されます。
• 24 時間を過ぎた後（および同期生成のリクエスト）でも、生成済みのファイルが残っていれば completed として返ります（ファイルの記録から組み立てるため、designId と files が中心になり、version / pageCount / createdAt / completedAt は含まれません）。
• 24 時間を過ぎた後の失敗は、次のように返ります。
  • 複数生成ですべてのファイルが失敗したリクエスト: 200 で status: "failed"、error.code は FILE_GENERATION_FAILED のまま返ります。ファイルごとの理由（failedFiles）は含まれません。
  • 単一生成の失敗: 失敗したリクエストにはファイルの記録が無いため、404 REQUEST_NOT_FOUND になります。
• 正常に生成した後にファイルが削除され、ファイルが 1 件も残っていないリクエストも 404 REQUEST_NOT_FOUND になります。

エラーレスポンス

ステータス	code	原因
404	REQUEST_NOT_FOUND	requestId が存在しない、別のワークスペースのもの、24 時間を過ぎた単一生成の失敗、または生成済みのファイルが削除されて残っていない。生成直後は、ジョブの記録を保存できなかったリクエストが生成中でも 404 になることがある（数秒おきに 1〜2 回確かめ直す）
429	RATE_LIMITED	300 req/min を超えた。Retry-After 秒待って再送

{
  "statusCode": 404,
  "code": "REQUEST_NOT_FOUND",
  "message": "Request not found: kZ3mP9qL2xV7nR4t",
  "error": "Not Found",
  "details": [],
  "docsUrl": "https://doc.re-port-flow.com/en/docs/guides/error-codes#request_not_found"
}

次のステップ

• 非同期ワークフロー - 状態 API を使った完了待ちのパターン
• PDF のダウンロード - 完了したファイルの取得
• Webhook 通知 - ポーリングせずに完了・失敗を受け取る
• エラーコード一覧