Idempotência e segurança de retry
Tente novamente com segurança a criação de tarefas de documento em tempos limite de rede usando cabeçalhos Idempotency-Key com escopo de projeto, e distinga-os do processo pago e despacho de provedor.
Criação de tarefa segura para reprodução#
POST /v1/tasks aceita um opcional Idempotency-Key (8–128 letras ASCII, dígitos, pontos, sublinhados, dois-pontos ou hífens; começa com uma letra ou dígito). Repetir uma chave para a mesma conta HQTools e projeto de API retorna a tarefa existente. Reutilizar a mesma chave para uma ferramenta diferente retorna 409 IDEMPOTENCY_KEY_REUSED.
curl -q --fail-with-body -X POST 'https://api.pdfhq.io/v1/tasks' \
-H 'x-api-key: YOUR_SERVER_SIDE_API_KEY' \
-H 'Idempotency-Key: job-20261025-00001' \
-H 'Content-Type: application/json' \
-d '{"tool":"compress"}'O ID da tarefa retornado é estável entre tentativas. As chaves têm escopo de conta e projeto de API e permanecem associadas à tarefa até que o registro subjacente seja removido. Crie uma nova chave para uma nova tarefa.
Regras de repetição diferentes para recursos diferentes#
Criação de tarefa: repetir usando a mesma Idempotency-Key após uma interrupção de rede. Processamento de tarefas: o ID de tarefa fixa já fornece idempotência de job/crédito de backend para opções idênticas; inspecione seu estado antes de tentar novamente. Trabalhos de IA: utilize uma citação aprovada pelo utilizador e uma Idempotency-Key estável conforme suportado pelo endpoint de IA. Envio de assinatura eletrônica: uma resposta incerta do provedor requer reconciliação de envelope; não reenvie cegamente uma solicitação de assinatura.
Uploads S3 assinados usam políticas de formulário POST de curta duração. Não envie x-api-key ou Idempotency-Key para S3. Uploads de armazenamento e estimativa de cotação não cobram créditos por si só; o processamento é que cobra.
