빈 표 내보내기(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)는 감지된 표마다 시트 하나를 가진 통합 문서 하나를 씁니다.
그 목록이 비면 둘 다 Output::no_content()를 반환하고 이것이 204로 매핑됩니다. 빈 .xlsx와 함께 오는 200은 성공으로 잘못 읽기 쉽습니다. 204는 "내보낼 것이 없다"는 뜻입니다.
204가 나오는 흔한 이유
- 산문만 있는 PDF: 열 정렬이 뚜렷하지 않은 서술형 텍스트입니다. PDF를 텍스트로나 PDF를 Markdown으로를 대신 쓰세요.
- 텍스트 레이어가 없는 스캔 페이지:
pdftotext출력이 비어 표가 나타나지 않습니다. 먼저 OCR(이 사이트에서는 Markdown 텍스트)을 돌리고, 그 단어들이 실제로 열을 이룰 때만 다시 시도하세요. - 선이나 이미지로만 그린 표: 뽑아낼 셀 텍스트가 없는 시각적 격자는 시트가 되지 않습니다.
- 지저분한 다단 잡지 레이아웃: 사람이 "표"라고 부를 블록을 휴리스틱이 놓치거나, 읽기 순서를 엉망으로 합칠 수 있습니다.
- 한 줄짜리 "표": 공백이 들어간 줄 하나는 절대 블록이 되지 않습니다. 표 형식 줄이 최소 두 개 필요합니다.
암호화된 파일은 추출 전에 권한 있는 비밀번호 해제가 필요합니다. 문서 정보나 내보내기가 파일을 열지 못하면 PDF 복구로 고치세요.
204가 아닌 것
204는 전송 실패도, 타임아웃도, "서버가 첨부를 빠뜨렸다"도 아닙니다. 성공적인 판단으로 보세요. 표 블록이 없다는 뜻입니다. 텍스트 레이어나 레이아웃을 바꾸지 않고 같은 파일을 그대로 다시 시도하면 또 204가 돌아옵니다. 스크립트는 빈 파일 이름이 아니라 상태 코드로 분기해야 합니다.
OCR이 주는 Markdown은 에이전트용 텍스트 추출이지 스프레드시트가 아닙니다. OCR 출력을 .md 파일에 붙여 넣은 뒤 나중에 열이 필요해져도, pdftotext -layout(또는 사람)이 홈으로 볼 수 있는 레이아웃이 있어야 합니다. 텍스트 레이어 없이 같은 스캔 PDF를 다시 내보내면 계속 204입니다.
다음에 할 일
- PDF를 열어 셀 텍스트를 선택할 수 있는지 확인합니다. 안 되면 OCR을 돌리고, 복구된 텍스트가 이 휴리스틱을 통과할 만큼 열 형태인지 판단하세요.
- 표가 여러 개일 것으로 보면 PDF를 Excel로(표마다 시트 하나)를, 평평한 파일 하나나 CSV 묶음이 필요하면 PDF를 CSV로를 고르세요.
- 페이지가 서술형이면 도구를 바꾸세요. 표 내보내기는 계속 204를 반환합니다.
- 에이전트나 파이프라인의 상태 처리를 쓴다면 204를 "표를 찾지 못함"으로 매핑하고, 일반적인 재시도 루프에 넣지 마세요.
- 단어만 필요하면 PDF를 텍스트로나 PDF를 Markdown으로에서 멈추세요. 산문에 스프레드시트 모양을 강제하면 204가 계속됩니다.
브라우저 경로에는 계정이 필요하지 않습니다. 같은 엔드포인트를 HTTP로 쓰려면 개발자를 보세요. 클라이언트가 POST를 두 번 할 수 있다면 재시도에 Idempotency-Key를 보내세요(Idempotency-Key).