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.

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:
- O armazenamento indexa a entrada por principal + chave. O principal vem de
X-API-KEY(comokey:…), senão deAuthorization(comoauth:…), senão do literalanon. Esses dois valores recebem hash (SHA-256) para formar a chave do mapa; o corpo da requisição não faz parte da chave. - 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. - 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).
- 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: truese 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.