Erro 401: "Embed token has been consumed" e os outros cinco

Um 401 na API de assinatura raramente significa o que parece. Antes de desconfiar da credencial, vale ler a mensagem: existem seis mensagens distintas ligadas ao token de embed — o token do signatário, diferente do token da sua aplicação — e cada uma tem uma causa e uma correção próprias. A mais comum de todas nem é um token com problema: é uma rota que só aceita o token do signatário, chamada com o Bearer do integrador. Este guia traz as seis, o que fazer em cada caso, e como reemitir um link de assinatura sem recriar nada nem gastar cota.

As seis mensagens

O caso mais comum: consumed

O link de assinatura vale uma vez. Depois que a pessoa conclui — ou que o token embutido é consumido de outra forma — reabrir a mesma URL devolve:

Isso soa como defeito e é o comportamento correto. Um link reutilizável seria uma credencial permanente circulando por e-mail, capaz de reabrir a sessão de assinatura de outra pessoa. O uso único é o que impede isso.

O efeito colateral é real, porém, e não é culpa de ninguém: a pessoa fecha a aba sem querer, o e-mail é encaminhado e alguém abre antes, o aplicativo de mensagens pré-carrega o endereço para gerar a pré-visualização. Nenhuma dessas situações deveria custar uma transação nova — e não custa:

Três propriedades que respondem às dúvidas previsíveis: não consome cota (reemitir não é enviar de novo), não estende o prazo (o expiresAt é o da sessão original), e só funciona em sessão ativa — uma concluída ou cancelada devolve 409, o que faz sentido, já que um link para uma sessão encerrada não autenticaria nada.

O 401 que não é sobre token: rota errada

Este é o caso que mais consome tempo, porque a mensagem não menciona embed token e a credencial está perfeita.

A API tem duas credenciais com públicos diferentes: o Bearer representa a sua aplicação; o token de embed representa a pessoa que assina. Seis rotas aceitam apenas o segundo — todas elas usadas pela página de assinatura:

A separação existe por um motivo substantivo: se o token da aplicação pudesse avançar etapas, quem enviou o documento poderia concluir a assinatura em nome de quem deveria assinar — e a evidência registraria, com todos os carimbos em ordem, um ato que a pessoa nunca praticou. O detalhamento está em os dois tokens da API.

Expired é diferente de consumed

Vale distinguir, porque a correção é oposta:

Se expired aparece com frequência, o problema não é de código: é o prazo escolhido. A janela padrão é de 72 horas e pode ir de 5 minutos a 7 dias, definida por sessão — os detalhes estão em todos os prazos da API. Vale também tratar o evento de prazo se aproximando, que permite lembrar o signatário antes de o link morrer.

Not found e invalid: quase sempre link truncado

Antes de investigar qualquer outra hipótese, confira se a URL chegou inteira. O segredo do signatário viaja como parâmetro na URL, e ele é longo — o suficiente para que:

• clientes de e-mail quebrem a linha no meio e o link vire dois pedaços;
• uma cópia manual pegue só até o primeiro espaço;
• um encurtador remova o que vem depois do ?.

A prevenção é entregar o link como link, e não como texto a ser copiado — e nunca montá-lo à mão a partir de pedaços. Use a URL que a API devolve, inteira. Montar manualmente é também a origem típica de missing required claims.

Quando o 401 é da sua credencial mesmo

Aí a mensagem é outra, e não fala em embed token. Duas causas dominam:

• Token de acesso vencido. Ele dura 900 segundos. Um pico de 401 logo depois de uma janela ociosa indica um token guardado além da validade — defeito de implementação, não incidente. Renove pelo expires_in devolvido, não por agenda fixa.
• Credencial pausada ou revogada. Chamadas com uma credencial pausada passam a falhar; a mudança leva até 60 segundos para valer em toda a frota. Confira o status no painel — ver rotação de credenciais.

Roteiro de diagnóstico

1. A mensagem fala em embed token? Se sim, é o token do signatário — use a tabela do topo.
2. Se não: a rota está na lista das seis? Então ela nunca vai aceitar o seu Bearer. Para consultar, troque pela rota de status.
3. Nem uma coisa nem outra? Verifique a validade do token e o status da credencial no painel.
4. É 403, e não 401? Então a credencial foi aceita e falta permissão — o problema é escopo, tratado em por que o seu token falha.

Para o catálogo completo dos códigos de erro, veja códigos de erro e tratamento de falhas. O painel também traz, ao lado de cada requisição que falhou, uma explicação em português e uma linha de como corrigir — descrito em o painel de API. E a visão geral da API de assinatura digital descreve os recursos citados aqui.

Perguntas Frequentes