エラーコード一覧

Re:port Flow API（PDF 生成・状態確認・ダウンロード・テンプレートのパラメータ取得）が返すエラーレスポンスには、機械判定用の code が必ず含まれます（例外として、413 と同期生成の 504 / 524 は API の手前の経路が返すことがあり、本文が JSON とは限らず code もありません。ステータスコードで判定してください。制限事項を参照）。message は人が読むための説明で、言語設定や将来の文言変更で変わるため、プログラムの分岐には code を使ってください。各コードの説明はこのページの #<code の小文字>（例: #plan_page_limit_exceeded）にあり、レスポンスの docsUrl からそのまま開けます。

ステータスコード別の対処とリトライの実装例は エラーハンドリング を参照してください。

エラーレスポンスの形式

{
  "statusCode": 403,
  "code": "PLAN_PAGE_LIMIT_EXCEEDED",
  "message": "Monthly page limit reached (100 pages). Upgrade your plan or wait until next month.",
  "error": "Forbidden",
  "details": [],
  "docsUrl": "https://doc.re-port-flow.com/en/docs/guides/error-codes#plan_page_limit_exceeded"
}

フィールド	型	説明
statusCode	number	HTTP ステータスコード
code	string	エラーコード（このページの見出し）。既存の値は改名・削除しない（追加はありうる）
message	string / string[]	人が読むための説明。通常は文字列。下記「message が配列になる場合」を参照
error	string	HTTP ステータスの理由句（Bad Request / Forbidden 等）
details	array	項目ごとの詳細。無ければ空配列 []
docsUrl	string	このページの該当コードへの URL
retryAfter	number	429 RATE_LIMITED と 409 FILE_NOT_READY のときだけ。再試行まで待つ秒数

言語（Accept-Language）

• 既定は英語です。
• リクエストの Accept-Language で最も優先度（q 値）の高い言語タグが ja または ja-*（例: ja-JP）のときだけ、message と details[].message のうち日本語訳があるものが日本語になり、docsUrl も日本語版のページ（https://doc.re-port-flow.com/docs/guides/error-codes#<code>）になります。
• 日本語訳が無い文言は、ja を指定しても英語のままです。例: FILE_NOT_READY・FILE_GENERATION_FAILED・REQUEST_NOT_FOUND・WEBHOOK_URL_NOT_ALLOWED の message、入力検証（VALIDATION_FAILED）の標準の文言（version must be an integer number など）、500 の汎用文言（Internal Server Error）。
• それ以外（未指定・*・英語・その他の言語）はすべて英語です。
• どちらの言語で返したかは、レスポンスヘッダー Content-Language: en / Content-Language: ja で分かります。
• code は言語によらず同じ値です。

curl -X POST https://api.re-port-flow.com/v1/file/sync/single \
  -H "appkey: your-application-key" \
  -H "Content-Type: application/json" \
  -H "Accept-Language: ja" \
  -d '{ ... }'

message が配列になる場合

リクエストボディの検証エラー（必須項目の欠落・型の誤り・ファイル名の禁止文字など）では、既存クライアントとの互換性のため message が文字列の配列のままです。このときの code は通常 VALIDATION_FAILED で、配列の全要素が同じ種類のエラー（例: ファイル名の禁止文字だけ）のときはその種類の code（例: FILE_NAME_INVALID）になります。それ以外のエラーでは message は文字列です。

message の型に依存せず処理したい場合は、code と details を使ってください。

details

details は次の形の配列です。

フィールド	説明
field	問題のある入力の場所。省略されることがある。例: version、content.fileName、contents.0.fileName、params.amount
expected	期待した型。省略されることがある。params の型の不一致では string / number / date / boolean / object / array
code	その項目単位のエラーコード。判別できたときだけ含まれる
message	その項目の説明

{
  "statusCode": 400,
  "code": "PARAMS_TYPE_MISMATCH",
  "message": "Parameter validation failed: \"amount\" must be a number",
  "error": "Bad Request",
  "details": [
    { "field": "params.amount", "expected": "number", "code": "PARAMS_TYPE_MISMATCH", "message": "\"amount\" must be a number" }
  ],
  "docsUrl": "https://doc.re-port-flow.com/en/docs/guides/error-codes#params_type_mismatch"
}

retryAfter と Retry-After

429（RATE_LIMITED）と 409（FILE_NOT_READY）では、Retry-After レスポンスヘッダーと本文の retryAfter に、再試行まで待つべき秒数が入ります（両者は同じ値）。この秒数だけ待てば、同じリクエストをそのまま再送できます。

5xx の message

5xx の message は内部情報（スタックトレース等）を含まない汎用の文言です（例: Internal Server Error）。続く場合は、発生日時とリクエスト内容を添えてサポートへ連絡してください。

コード一覧（早見表）

code	主な HTTP ステータス	概要
AUTH_HEADER_MISSING	412	appkey ヘッダーも Authorization ヘッダーも無い、または appkey ヘッダーの形式が不正
INVALID_CREDENTIALS	401	アプリケーションキー・トークンが無効
WORKSPACE_MISMATCH	403	サムネイル生成: リクエストの workspaceId が認証情報のワークスペースと一致しない
WORKSPACE_SCOPE_VIOLATION	403	認証したワークスペース以外へ出力しようとした
WORKSPACE_ROLE_DENIED	403	OAuth ユーザーにワークスペースでの権限が無い
PLAN_NOT_FOUND	403	ワークスペースのプラン情報が無い
ACCESS_DENIED	403	アクセスが拒否された（生成・ダウンロード API からは返らない）
PLAN_PAGE_LIMIT_EXCEEDED	403	月間の出力ページ数の上限に達した
ACTIVE_PLAN_NOT_FOUND	404	ワークスペースに有効なプランが無い
RATE_LIMITED	429	レート制限を超えた
DESIGN_NOT_FOUND	404	パラメータ取得（version 指定なし）: テンプレートが存在しない
DESIGN_VERSION_NOT_FOUND	404	生成・パラメータ取得（version 指定あり）: テンプレートまたはバージョンが存在しない
VERSION_NOT_FOUND	404	生成・パラメータ取得 API からは返らない
VALIDATION_FAILED	400	リクエストボディの検証エラー
PARAMS_TYPE_MISMATCH	400	params の値の型がテンプレートと合わない
PARAMS_NOT_OBJECT	400	params / passthrough が JSON オブジェクトではない
PARAMS_CIRCULAR_REFERENCE	400	params に循環参照がある
PARAMS_TOO_LARGE	400	params が大きすぎる
FILE_NAME_INVALID	400	ファイル名に使えない文字がある
FILE_NAME_DUPLICATED	400	contents 内でファイル名が重複している
TOO_MANY_CONTENTS	400	contents が 100 件を超えている
WEBHOOK_URL_NOT_ALLOWED	400	webhookUrl が登録済みの有効なエンドポイントではない
REQUEST_NOT_FOUND	404	状態 API: requestId が見つからない（ID の誤り・別ワークスペース・記録の期限切れ・削除済み）
FILE_NOT_FOUND	404	ダウンロード: ID の誤り・別ワークスペースの ID・失敗から 24 時間を過ぎた単一生成・出力の削除
FILE_NOT_READY	409	ダウンロード: まだ生成中
FILE_GENERATION_FAILED	422	ダウンロード: 生成に失敗したリクエスト
JOB_NOT_FOUND	404	ジョブが見つからない
RENDER_QUEUE_FULL	503	生成の待ち行列が満杯
CONVERT_QUEUE_FULL	503	画像変換・AI 推定の待ち行列が満杯（アプリ内機能）
PARTIAL_FAILURE	（file.failed Webhook のみ）	複数生成の一部が失敗した
GENERATION_INTERRUPTED	（状態 API のみ）	生成処理が途中で止まった

このほか、アプリ内の機能で使うコード（PDF_CONVERSION_FAILED など）と、個別のコードを持たないエラーに付く汎用コード（BAD_REQUEST など）があります。

認証・認可

AUTH_HEADER_MISSING

• HTTP ステータス: 412 Precondition Failed
• 原因: appkey ヘッダーも Authorization: Bearer <token> ヘッダーも送られていない。または appkey ヘッダーはあるが、値の形式検証に通らなかった。
• 対処: どちらかの認証ヘッダーを正しい値で付けて再送する（API キー認証 / OAuth 2.0 認証）。

412 のままにしている理由

認証ヘッダーが無いときのステータスは、既存クライアントとの互換性のため従来どおり 412 です（401 には変更していません）。401 と区別したい場合は code を見てください。

INVALID_CREDENTIALS

• HTTP ステータス: 401 Unauthorized
• 原因: アプリケーションキーまたはアクセストークンが無効。トークンに必要なスコープ（pdf:generate）が無い、またはトークンがワークスペースに結び付いていない場合も含む。x-workspace-id ヘッダーを送り、その値がアプリケーションキーのワークスペースと一致しない場合もこのコードになる。
• 対処: キーの値・再生成の有無、トークンの有効期限とスコープを確認する。

WORKSPACE_MISMATCH

• HTTP ステータス: 403 Forbidden
• 原因: サムネイル生成のリクエストボディで指定した workspaceId が、認証情報のワークスペースと一致しない。PDF 生成・状態確認・ダウンロード・パラメータ取得の API はこのコードを返さない（x-workspace-id ヘッダーの不一致は 401 INVALID_CREDENTIALS）。
• 対処: 認証に使ったキー・トークンと同じワークスペースを指定する（省略すると認証情報のワークスペースが使われる）。

WORKSPACE_SCOPE_VIOLATION

• HTTP ステータス: 403 Forbidden
• 原因: 認証したワークスペース以外を出力先にしようとした。
• 対処: 出力先を認証したワークスペースにする。

WORKSPACE_ROLE_DENIED

• HTTP ステータス: 403 Forbidden
• 原因: OAuth で認可したユーザーが、そのワークスペースでこの操作を行う権限を持っていない。
• 対処: ワークスペースの管理者にロールを確認してもらう。

PLAN_NOT_FOUND

• HTTP ステータス: 403 Forbidden
• 原因: ワークスペースのプラン情報が見つからない。
• 対処: 管理画面の ワークスペース設定 → プラン を確認する。解決しない場合はサポートへ連絡する。

ACCESS_DENIED

• HTTP ステータス: 403 Forbidden
• 原因: アクセスが拒否された。コード一覧には残っていますが、PDF 生成・状態確認・ダウンロードの API は現在このコードを返しません。別のワークスペースの requestId をダウンロードしようとした場合は、存在を知らせないため 404 FILE_NOT_FOUND（状態 API では 404 REQUEST_NOT_FOUND）になります。
• 対処: 受け取った場合は、発生日時とリクエスト内容を添えてサポートへ連絡する。

プラン・レート制限

PLAN_PAGE_LIMIT_EXCEEDED

• HTTP ステータス: 403 Forbidden
• 原因: 今月の PDF 出力ページ数の上限に達した（上限は出力回数ではなく出力ページ数の合計で数える）。英語の message は Monthly page limit reached (<上限> pages). Upgrade your plan or wait until next month.。
• 対処: プランをアップグレードするか、翌月まで待つ。再送しても同じ月のうちは成功しない。

ACTIVE_PLAN_NOT_FOUND

• HTTP ステータス: 404 Not Found
• 原因: ワークスペースに有効なプランが無い。
• 対処: 管理画面でプランの状態を確認する。

RATE_LIMITED

• HTTP ステータス: 429 Too Many Requests
• 原因: ワークスペース単位のレート制限を超えた（同期生成 30 req/min、非同期生成・ダウンロード等 100 req/min、状態 API 300 req/min。詳細は 制限事項）。
• 対処: Retry-After ヘッダー（本文の retryAfter も同じ値）の秒数だけ待ってから再送する。

テンプレート

DESIGN_NOT_FOUND

• HTTP ステータス: 404 Not Found
• 原因: テンプレートのパラメータ取得で version を指定しなかったとき、テンプレート ID（designId）が存在しない（または別のワークスペースのもの）。テンプレート ID は 0eUDdgAjNXrrItA2 のような16文字の英数字で、形式チェックは行わないため、ID の誤りは 400 ではなく 404 になる。PDF 生成と、version を指定したパラメータ取得では、存在しない designId は DESIGN_VERSION_NOT_FOUND になる。
• 対処: 管理画面からテンプレート ID をコピーし直す。

DESIGN_VERSION_NOT_FOUND

• HTTP ステータス: 404 Not Found
• 原因: PDF 生成、または version を指定したパラメータ取得で、指定したテンプレートとバージョンの組み合わせが存在しない。テンプレート ID（designId）自体が存在しない・別のワークスペースのものである場合と、バージョンだけが存在しない場合のどちらもこのコードになる。
• 対処: designId と version の組み合わせを確認する。designId だけを確かめたい場合は、version を付けずにパラメータ取得を呼ぶ（テンプレートが無ければ DESIGN_NOT_FOUND）。

VERSION_NOT_FOUND

• HTTP ステータス: 404 Not Found
• 原因: コード一覧には残っていますが、PDF 生成・パラメータ取得の API は現在このコードを返しません。存在しないバージョンを指定した場合は DESIGN_VERSION_NOT_FOUND になります。
• 対処: 受け取った場合は、発生日時とリクエスト内容を添えてサポートへ連絡する。

入力

VALIDATION_FAILED

• HTTP ステータス: 400 Bad Request
• 原因: リクエストボディの検証エラー（必須項目の欠落、型の誤り、許可されていないプロパティ等）。message は文字列の配列。
• 対処: details[].field が指す項目を直す。

PARAMS_TYPE_MISMATCH

• HTTP ステータス: 400 Bad Request（非同期生成では状態 API の error.code。生成リクエストで webhookUrl を指定した場合は file.failed Webhook の error.code にも入る）
• 原因: params の値の型がテンプレートのパラメータの型と合わない。
• 対処: details[].field（params.<キー>）と details[].expected を見て値を直す。各パラメータの型は テンプレートのパラメータ取得 で確認できる。

PARAMS_NOT_OBJECT

• HTTP ステータス: 400 Bad Request
• 原因: params または passthrough が JSON オブジェクトではない（配列・文字列・解析できない JSON 文字列など）。
• 対処: { "key": value } 形式のオブジェクトを送る。

PARAMS_CIRCULAR_REFERENCE

• HTTP ステータス: 400 Bad Request
• 原因: params に循環参照が含まれている。
• 対処: 循環しない構造にする。

PARAMS_TOO_LARGE

• HTTP ステータス: 400 Bad Request
• 原因: params のサイズが上限（1,000,000 bytes）を超えている。
• 対処: データを減らすか、リクエストを分割する。

FILE_NAME_INVALID

• HTTP ステータス: 400 Bad Request
• 原因: fileName に / \ : * ? " < > | または制御文字（0x00–0x1F）が含まれている。スペースや日本語は使える。
• 対処: これらの文字を除去または置換する（例: fileName.replace(/[\/\\:*?"<>|\x00-\x1F]/g, '_')）。

FILE_NAME_DUPLICATED

• HTTP ステータス: 400 Bad Request
• 原因: 複数生成の contents 内で fileName が重複している（大文字・小文字は区別しない）。
• 対処: ファイルごとに一意の名前を付ける。

TOO_MANY_CONTENTS

• HTTP ステータス: 400 Bad Request
• 原因: contents が 1 リクエストあたりの上限（100 件）を超えている。
• 対処: リクエストを分割する。

WEBHOOK_URL_NOT_ALLOWED

• HTTP ステータス: 400 Bad Request
• 原因: リクエストの webhookUrl が、ワークスペースに登録済みで有効な Webhook エンドポイントの URL と一致しない。
• 対処: 先に Webhook エンドポイントとして登録・有効化してから指定する（Webhook 通知）。

生成・取得

REQUEST_NOT_FOUND

• HTTP ステータス: 404 Not Found
• 原因: 状態 API で指定した requestId が見つからない。次の場合にこのコードになる。
  • requestId の誤り、または別のワークスペースの requestId
  • 単一生成の失敗から 24 時間を過ぎた（ジョブの記録が消え、失敗したリクエストにはファイルの記録も無い）
  • 生成直後で、ジョブの記録を保存できなかったリクエスト（生成中でも 404 になる。数秒おきに 1〜2 回確かめ直す）
  • 正常に生成した後にファイルが削除され、1 件も残っていない
  • 複数生成ですべてのファイルが失敗したリクエストは、24 時間を過ぎても 404 ではなく 200 status: "failed"（error.code は FILE_GENERATION_FAILED。ファイルごとの理由は含まれない）になる
• 対処: 生成 API のレスポンスの requestId を使っているか、認証情報のワークスペースが生成時と同じかを確認する。

FILE_NOT_FOUND

• HTTP ステータス: 404 Not Found
• 原因: ダウンロードで指定した requestId / fileId が見つからない。404 は、ID の誤り、別のワークスペースの ID（存在を知らせないため 403 ではなく 404）、失敗から 24 時間を過ぎた単一生成（失敗した単一生成にはファイルの記録が無く、ジョブの記録も 24 時間で消えるため、失敗とは判定できない）、または出力が削除された（正常に生成した後にファイルが消えた）ことを意味する。生成中は通常 409 FILE_NOT_READY、生成失敗は 422 FILE_GENERATION_FAILED になるが、生成中でもジョブの記録が無い場合（記録の保存に失敗した等）は 404 になる。
• 対処: 生成 API のレスポンスの requestId / fileId を使っているか、認証情報のワークスペースが生成時と同じかを確認する。状態 API でリクエストの状態も確認できる。

FILE_NOT_READY

• HTTP ステータス: 409 Conflict
• 原因: ダウンロード対象のファイルがまだ生成中。
• 対処: Retry-After（現在は 2 秒）待ってから再送するか、状態 API で完了を待つ。

FILE_GENERATION_FAILED

• HTTP ステータス: 422 Unprocessable Entity（ダウンロード）。状態 API の error.code にも使う（生成リクエストで webhookUrl を指定した場合は file.failed Webhook の error.code にも入る）
• 原因: そのリクエストの PDF 生成が失敗した。複数生成ですべてのファイルが失敗した場合もこのコード。
• 対処: 状態 API の error / failedFiles で理由を確認し、原因を直して新しいリクエストとして生成し直す。

JOB_NOT_FOUND

• HTTP ステータス: 404 Not Found
• 原因: /v1/jobs/{id} で指定したジョブが見つからない。
• 対処: ジョブ ID を確認する。

RENDER_QUEUE_FULL

• HTTP ステータス: 503 Service Unavailable
• 原因: PDF 生成が混み合っていて待ち行列が満杯。
• 対処: 時間をおいて再試行する。

PARTIAL_FAILURE

• HTTP ステータス: なし（HTTP エラー応答には出ない）
• 原因: 複数生成（/v1/file/async/multiple）で一部のファイルだけ失敗した。生成リクエストで webhookUrl を指定した場合だけ、その宛先への file.failed Webhook の error.code に現れ、files には失敗したファイルだけが入る（Webhook 通知）。成功したファイルは file.completed で通知される。状態 API では status: "completed" のまま、失敗したファイルが failedFiles に入る。
• 対処: 失敗したファイルだけを直して生成し直す。

GENERATION_INTERRUPTED

• HTTP ステータス: なし（状態 API の error.code のみ）
• 原因: 生成処理が進まないまま止まった（30 分以上進捗が無い）。
• 対処: 同じ内容で生成し直す。続く場合はサポートへ連絡する。

アプリ内機能のコード

API から直接呼ぶ生成エンドポイントでは通常返りませんが、エディタ等のアプリ内機能で使うコードです。

CONVERT_QUEUE_FULL

HTTP 503。画像変換・AI 推定の同時受付数が上限に達し、待ち行列も満杯。時間をおいて再試行する。PDF 生成の待ち行列（RENDER_QUEUE_FULL）とは別。

PDF_CONVERSION_FAILED

PDF への変換に失敗した。時間をおいて再試行し、続く場合はサポートへ連絡する。

OUTPUT_TARGET_MISSING

出力先（outputCategory または outputPath）が指定されていない。

EMPTY_PDF

PDF データが空だった。

INVALID_PDF

ファイルが PDF として正しくない。

THUMBNAIL_ENQUEUE_FAILED

サムネイル生成ジョブの登録に失敗した。時間をおいて再試行する。

汎用コード

個別のコードを持たないエラーには、HTTP ステータスに応じた汎用コードが付きます。表に無い 4xx は BAD_REQUEST、5xx は INTERNAL_ERROR として扱われます。

BAD_REQUEST

HTTP 400。リクエストが不正。

UNAUTHORIZED

HTTP 401。認証に失敗した。

FORBIDDEN

HTTP 403。この操作を行う権限が無い。

NOT_FOUND

HTTP 404。リソースが見つからない。

REQUEST_TIMEOUT

HTTP 408。リクエストがタイムアウトした。重い帳票は非同期エンドポイントを使う。

CONFLICT

HTTP 409。現在の状態と競合している。

PRECONDITION_FAILED

HTTP 412。必要なリクエストヘッダーが無いか不正。

PAYLOAD_TOO_LARGE

HTTP 413。リクエストボディが大きすぎる。

UNPROCESSABLE_ENTITY

HTTP 422。リクエストを処理できなかった。

CLIENT_CLOSED_REQUEST

HTTP 499。クライアントがリクエストを中断した。

INTERNAL_ERROR

HTTP 500。サーバー内部のエラー。時間をおいて再試行し、続く場合はサポートへ連絡する。

SERVICE_UNAVAILABLE

HTTP 503。サービスが一時的に利用できない。時間をおいて再試行する。