How-to3 min de leitura

Exportação de tabela vazia (204): seu PDF provavelmente não tem colunas

PDF para Excel e PDF para CSV retornam HTTP 204 quando nenhum bloco de tabela é detectado: é intencional, não uma falha. Faça OCR nas digitalizações antes.

By the PDF123 team · Updated 2026-10-02
Exportação de tabela vazia (204): seu PDF provavelmente não tem colunas

Se o PDF para Excel ou o PDF para CSV termina com HTTP 204 No Content e nenhum corpo para download, o extrator encontrou zero blocos de tabela. Esse status é proposital: a API se recusa a inventar uma planilha vazia quando a heurística de layout não vê colunas.

O que o extrator procura

As duas ferramentas compartilham o mesmo fluxo. O servidor roda pdftotext -layout, divide as páginas nos limites de form-feed e agrupa as linhas que parecem blocos em colunas. Uma linha conta como tabular quando contém pelo menos dois espaços consecutivos (as calhas de coluna do modo layout). Um bloco só é mantido quando tem pelo menos duas dessas linhas; uma linha espaçada isolada é descartada, para que títulos não virem "tabelas" de uma linha só.

O PDF para CSV (POST /api/v1/convert/pdf/csv) gera um CSV por tabela detectada (nomeado com a página e o índice da tabela), ou um ZIP quando há várias. O PDF para Excel (POST /api/v1/convert/pdf/xlsx) grava uma pasta de trabalho com uma planilha por tabela detectada.

Quando essa lista está vazia, os dois retornam Output::no_content() mapeado para 204. Um 200 com um .xlsx em branco seria mais fácil de interpretar como sucesso; o 204 significa "nada para exportar".

Motivos comuns para receber 204

  • PDF só de prosa: texto narrativo, sem alinhamento claro de colunas. Use PDF para texto ou PDF para Markdown.
  • Páginas digitalizadas sem camada de texto: a saída do pdftotext fica vazia, então nenhuma tabela aparece. Aplique OCR primeiro (o texto sai em Markdown neste site) e só tente a exportação de novo se as palavras realmente formarem colunas.
  • Tabelas desenhadas apenas com linhas ou imagens: grades visuais sem texto de célula extraível não viram planilhas.
  • Diagramações confusas de revista, com várias colunas: a heurística pode perder blocos que uma pessoa chamaria de tabela, ou embaralhar a ordem de leitura.
  • "Tabelas" de uma linha só: uma linha espaçada nunca vira bloco; são necessárias pelo menos duas linhas tabulares.

Arquivos criptografados precisam de um Desbloquear autorizado antes da extração. Repare um arquivo danificado com o Repair se o Get Info ou a exportação não conseguirem abri-lo.

O que o 204 não é

O 204 não é falha de transporte, não é timeout e não é "o servidor esqueceu o anexo". Trate-o como uma decisão bem-sucedida: nenhum bloco de tabela. Repetir o mesmo arquivo, sem mudar a camada de texto nem o layout, devolve 204 outra vez. Os scripts devem decidir pelo código de status, não por um nome de arquivo vazio.

O Markdown do OCR é uma extração de texto para agentes, não uma planilha. Se você colar a saída do OCR num .md e depois precisar de colunas, ainda vai precisar de um layout que o pdftotext -layout (ou uma pessoa) enxergue como calhas; reexportar a mesma digitalização sem camada de texto continuará devolvendo 204.

O que fazer em seguida

  1. Abra o PDF e confirme que consegue selecionar o texto das células. Se não conseguir, aplique OCR e depois decida se o texto recuperado tem colunas suficientes para essa heurística.
  2. Prefira o PDF para Excel quando esperar várias tabelas (uma planilha para cada). Prefira o PDF para CSV para um arquivo único e simples, ou um ZIP de CSVs.
  3. Se a página é narrativa, troque de ferramenta; a exportação de tabela vai continuar devolvendo 204.
  4. No tratamento de status de um agente ou pipeline, mapeie 204 para "nenhuma tabela detectada", não para um laço genérico de novas tentativas.
  5. Se você só precisa das palavras, pare no PDF para texto ou no PDF para Markdown; forçar formato de planilha sobre prosa vai continuar devolvendo 204.

O caminho pelo navegador não exige conta. Os mesmos endpoints por HTTP: Desenvolvedores. Envie um Idempotency-Key nas novas tentativas se o seu cliente puder fazer dois POST (Idempotency-Key).

Open tool
Process in the browser — no watermark, files removed after the job.
Open tool