Product3 min de leitura

Idempotency-Key: novas tentativas seguras em tarefas de PDF

Envie Idempotency-Key nos POST sob /api/v1/. PDF123 cacheia 24 h as respostas corretas em memória do processo; o reenvio não roda e dá Idempotency-Replayed: true.

By the PDF123 team · Updated 2026-09-30
Idempotency-Key: novas tentativas seguras em tarefas de PDF

Timeouts de rede e novas tentativas do cliente são normais em uploads multipart de PDF. Sem uma chave de idempotência, um segundo POST pode executar outra vez o mesmo merge, OCR ou compress, duplicando o upload e o tempo de processamento. Com Idempotency-Key, o PDF123 consegue reapresentar a primeira resposta bem-sucedida.

O que o middleware faz

O middleware do servidor, em pdfx-server, se aplica apenas a chamadas que alteram estado: POST em caminhos sob /api/v1/ (incluindo /api/v1/pipeline). GET e outros métodos passam sem alteração. Se a requisição não traz o cabeçalho Idempotency-Key (ou ele fica vazio depois de remover os espaços), a operação roda normalmente, sem consulta ao cache.

Quando o cabeçalho está presente:

  1. O armazenamento indexa a entrada por principal + chave. O principal vem de X-API-KEY (como key:…), senão de Authorization (como auth:…), senão do literal anon. Esses dois valores recebem hash (SHA-256) para formar a chave do mapa; o corpo da requisição não faz parte da chave.
  2. Num acerto de cache dentro de 24 horas, o middleware devolve o status, o content type, o content disposition e o corpo armazenados, e define Idempotency-Replayed: true.
  3. Num erro de cache, a requisição segue adiante. Apenas respostas bem-sucedidas são guardadas em buffer (respostas de falha não são cacheadas para reapresentação).
  4. Os corpos de resposta são guardados em buffer até 100 MiB, para que uma reapresentação consiga reenviar os bytes do arquivo. Um corpo que não cabe não pula o cache em silêncio: essa requisição devolve HTTP 500, então uma resposta acima do limite falha em vez de passar sem cache.

Tarefas que falharam podem ser repetidas com segurança usando a mesma chave: como as falhas não são armazenadas, a próxima tentativa pode dar certo e então virar o resultado em cache. Não reutilize uma chave para um arquivo ou parâmetros diferentes; o cache não aplica hash ao corpo, apenas ao principal e à chave. Dois chamadores que não compartilham nem chave de API nem Authorization não colidem por acidente, mas chamadores anônimos compartilham o principal anon e por isso precisam escolher chaves distintas.

Como enviar

Escolha uma cadeia opaca e estável por tarefa lógica (um UUID serve):

curl -X POST "https://pdf123.xyz/api/v1/misc/compress-pdf" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -F "[email protected]"

Funciona tanto para chamadores anônimos quanto para quem usa chave de API. Fluxos que encadeiam watermark e depois compress ainda devem enviar uma chave por requisição HTTP que você quer deduplicar, incluindo cada etapa se você as enviar separadamente, ou uma chave para uma única chamada a /api/v1/pipeline.

Tarefas pontuais no navegador, nas páginas de ferramenta (Comprimir, OCR, …), não exigem que você invente uma chave; o cabeçalho importa para clientes que repetem chamadas. O skill publicado em /skills/pdf123.md mostra um Idempotency-Key num exemplo de pipeline pelo mesmo motivo.

Padrões de cliente que funcionam

  • Gere a chave antes do primeiro POST e reutilize-a nas novas tentativas após timeout daquela mesma tarefa lógica.
  • Em caso de sucesso, verifique Idempotency-Replayed: true se precisar saber se a resposta voltou a executar a operação ou veio do cache.
  • Troque a chave quando o arquivo, a operação ou os parâmetros mudarem, mesmo que o principal continue o mesmo.
  • Para /api/v1/pipeline, uma única chave cobre o POST inteiro do pipeline, não cada etapa interna.

O que a reapresentação não é

A reapresentação não é uma fila de tarefas durável. O armazenamento é local ao processo (um HashMap atrás de um mutex), com TTL de 24 horas. Depois de expirar, ou depois de um reinício de processo que derruba o mapa em memória, a mesma chave executa a operação de novo. Implantações com várias instâncias não compartilham esse mapa, a menos que você coloque um armazenamento compartilhado na frente; o middleware de hoje é por processo.

Trate Idempotency-Replayed: true como prova de que a resposta veio do cache, não como registro permanente. Ele não significa que o PDF foi reprocessado e não estende o TTL.

Mais detalhes da superfície: Desenvolvedores e Feito para agentes de IA. Páginas de ferramenta como o Comprimir continuam disponíveis para tarefas pontuais no navegador, sem inventar chaves.

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