空の表エクスポート(204):その PDF には列が無い可能性が高い
PDF から Excel と PDF から CSV は、表ブロックが検出されないと HTTP 204 を返す。クラッシュではなく意図的な判断だ。スキャンは先に OCR し、散文だけの PDF は空のままになる。

PDF から Excel や PDF から CSV が HTTP 204 No Content で終わり、ダウンロードの本体が無いなら、抽出器が表ブロックを一つも見つけなかったということだ。このステータスは意図的である。レイアウトのヒューリスティックが列を見ないとき、API は空のスプレッドシートを発明することを拒む。
抽出器が探しているもの
両ツールは同じパイプラインを共有する。サーバーは pdftotext -layout を走らせ、フォームフィードの境界でページを分割し、列状のブロックに見える行をまとめる。行が表形式と数えられるのは、連続するスペースが少なくとも二つあるときだ(layout モードの列の溝)。ブロックが保持されるのは、そうした行が少なくとも二行あるときだけである。スペースを含む一行だけの行は捨てるので、見出しが一行の「表」になることはない。
PDF から CSV(POST /api/v1/convert/pdf/csv)は検出した表ごとに CSV を一つ出力し(ページ番号と表の索引で命名される)、複数あれば ZIP にする。PDF から Excel(POST /api/v1/convert/pdf/xlsx)は検出した表ごとにシートを持つワークブックを一つ書く。
そのリストが空のとき、どちらも 204 に対応付けられる Output::no_content() を返す。空の .xlsx を伴う 200 は成功と誤読されやすい。204 は「エクスポートするものが無い」という意味だ。
204 になるよくある理由
- 散文のみの PDF:列の揃えがはっきりしない叙述文。PDF からテキスト や PDF から Markdown を使う。
- テキスト層の無いスキャンページ:
pdftotextの出力が空なので、表は現れない。先に OCR(本サイトでは Markdown テキスト)を走らせ、語が実際に列を成すときだけ再試行する。 - 線や画像として描かれた表:見た目は格子でも、抽出できるセルのテキストが無ければシートにはならない。
- 雑然とした多段組みの誌面レイアウト:ヒューリスティックが、人が「表」と呼ぶブロックを取り逃したり、読み順をひどく混ぜたりすることがある。
- 一行だけの「表」:スペースを含む一行はブロックにならない。表形式の行が少なくとも二行必要だ。
暗号化されたファイルは抽出の前に正当な パスワードの解除 が必要だ。情報取得やエクスポートがファイルを開けない場合は 修復 で破損を直す。
204 がそうではないもの
204 は転送の失敗でも、タイムアウトでも、「サーバーが添付を忘れた」のでもない。成功した判断として扱う。表ブロックが無い、という判断だ。テキスト層やレイアウトを変えずに同一のファイルを再試行すれば、また 204 が返る。スクリプトは空のファイル名ではなくステータスコードで分岐すべきだ。
OCR の Markdown はエージェント向けのテキスト抽出であり、スプレッドシートではない。OCR の出力を .md ファイルに貼り、後から列が必要になっても、pdftotext -layout(または人間)が溝として見えるレイアウトが要る。テキスト層の無い同じスキャン PDF を再度エクスポートしても、204 が返り続ける。
次にすること
- PDF を開き、セルのテキストを選択できるか確認する。できなければ OCR し、復元されたテキストがこのヒューリスティックにとって十分に列状かを判断する。
- 複数の表を想定するなら PDF から Excel(表ごとにシート一つ)。単一の平坦なファイルや CSV の ZIP が欲しいなら PDF から CSV。
- ページが叙述ならツールを変える。表のエクスポートは 204 を返し続ける。
- エージェントやパイプラインの状態処理では、204 を「表が検出されなかった」に対応付け、汎用の再試行ループにしない。
- 語だけが必要なら PDF からテキスト や PDF から Markdown で止める。散文にスプレッドシートの形を強いても 204 が返り続ける。
ブラウザの経路にアカウントは不要だ。同じエンドポイントを HTTP から使う方法は 開発者向け にある。クライアントが二度 POST しうるなら、再試行に Idempotency-Key を送る(Idempotency-Key)。