Erro 409: conflito de estado, não de dados
O 409 é o código mais informativo da API e o menos aproveitado. Ele não diz que o seu dado está errado — diz que a operação é válida e não cabe no estado atual do objeto. Cancelar algo já cancelado, emitir link para uma sessão concluída, acrescentar um signatário que já está no envelope: em todos esses casos a requisição está bem formada e o problema é o momento. A consequência prática é que repetir nunca resolve, e a correção quase sempre começa por consultar o estado antes de agir.
Em uma linha: 409 é operação certa na hora errada. O dado está bom, o objeto é que não está no estado que permite aquilo. Repetir não muda o estado — a correção é consultar antes, ou tratar o caso de negócio que o estado revela.
Os casos que aparecem
| Situação | Por que 409 | O que fazer |
|---|---|---|
| Emitir link para sessão encerrada | Só sessão ativa aceita link novo | Entregar o documento assinado, não um link |
| Cancelar transação já encerrada | Estado terminal não aceita cancelamento | Conferir o estado — pode já estar assinada |
| Signatário repetido no envelope | A mesma pessoa duas vezes é recusada | Deduplicar a lista de origem |
| Índice de signatário já ocupado | A posição já foi preenchida | Ler o envelope e continuar de onde parou |
| Etapa já concluída | Concluir de novo não é possível | Seguir para a próxima etapa |
O mais comum: sessão que não está mais ativa
A mensagem inclui o estado atual, o que já é meio diagnóstico. E a regra é substantiva, não burocrática: um link de assinatura para uma sessão encerrada não autenticaria nada — não há mais ato a praticar.
O pedido por trás disso costuma ser outro, mal traduzido. Quando alguém pede "manda o link de novo" sobre um documento já assinado, o que a pessoa quer é ver o que assinou. Isso não é um link de assinatura:
| O que a pessoa quer | O caminho certo |
|---|---|
| Assinar, e perdeu o link (sessão ativa) | Emitir link novo — sem consumir cota |
| Ver o documento assinado de um envelope | Carimbo combinado do envelope |
| Ver o documento de uma transação avulsa | Download da transação |
| A prova formal do ato | Pacote de evidências |
Se a sessão está ativa e o link foi só consumido, aí sim é reemissão — e a mensagem seria outra, um 401 de token consumido, tratado em o erro 401 e o token de embed.
Cancelamento em estado terminal
Uma transação em estado terminal — concluída, cancelada ou expirada — não aceita cancelamento. O 409 aqui é frequentemente um sinal de negócio disfarçado de erro técnico: a coisa que você queria cancelar pode já ter sido assinada.
Vale tratar esse caso explicitamente em vez de registrar como falha. "Tentativa de cancelar um documento que já havia sido assinado" é um evento que alguém precisa ver — provavelmente a mesma pessoa que pediu o cancelamento.
Signatário repetido
A mesma pessoa não pode ocupar duas posições no mesmo envelope, e uma posição já preenchida não aceita outra sessão. Em fluxos que montam envelopes a partir de uma lista — planilha, consulta ao CRM, seleção na interface — a causa quase sempre é duplicidade na origem: a mesma pessoa aparece duas vezes na fonte.
A correção é deduplicar antes de enviar, e não tratar o 409 como aceitável. Vale lembrar que a cota do envelope é debitada na criação: descobrir a duplicidade depois significa um envelope criado que talvez precise ser refeito.
Eventos fora de ordem: a causa que não é sua
Integrações dirigidas por webhook produzem uma classe própria de 409, e ela costuma confundir porque o código parece correto.
A ordem de chegada dos eventos não é garantida. Um receptor que reage imediatamente a cada evento pode agir sobre um objeto que já avançou — tentando concluir algo concluído, ou cancelando o que já terminou. O resultado é um 409 legítimo produzido por uma condição de corrida, não por um defeito de lógica.
As defesas são as de sempre em processamento de eventos: manipulador idempotente, tolerância a desordem, e reconciliação periódica contra a API em vez de confiar apenas no fluxo de eventos. O desenho está em webhooks em fila: ack rápido e reprocessamento.
409 não é 422
São vizinhos e a distinção orienta a correção:
- 422 — o conteúdo enviado não serve. Documento corrompido, imagem sem rosto. Corrige-se mudando o que você envia.
- 409 — o conteúdo está bom, o objeto não está no estado certo. Corrige-se mudando quando você envia, ou aceitando o que o estado diz.
Os dois compartilham uma propriedade: repetir não resolve nenhum deles. Se o seu wrapper de nova tentativa trata qualquer erro como transitório, ambos viram laços que só gastam requisições — e podem levar ao 429, somando um segundo problema ao primeiro. O 422 está detalhado em documento recusado e recurso não habilitado.
O dano mais comum associado ao 409
Não recrie por causa de um 409. A recusa em si não cria nada e não consome cota. Mas quem a interpreta como "falhou, vou criar de novo" acaba criando um segundo envelope — e esse consome um documento do plano, que não é devolvido no cancelamento. O 409 quase sempre significa que o objeto que você procura já existe e está adiante, não que ele falhou.
O que implementar
- Consulte o estado antes de operações destrutivas. Uma leitura barata transforma um erro num ramo de decisão.
- Não repita 409 automaticamente. Trate como terminal e ramifique.
- Leia o estado que vem na mensagem. Ele diz o que aconteceu com o objeto, e frequentemente responde a pergunta do usuário.
- Torne o manipulador de eventos idempotente e tolerante a desordem.
- Deduplique listas de signatários antes de montar envelopes.
- Registre 409 como evento de negócio, não como erro de sistema — quase sempre há alguém que precisa saber.
Para o catálogo completo, veja códigos de erro e tratamento de falhas, e para o runbook de sessões vencidas, sessão expirada: reenviar, cancelar ou recriar. Os estados possíveis de cada objeto estão descritos na visão geral da API de assinatura digital.
Perguntas Frequentes
O que significa "Session cannot be linked in status"?
Que você pediu um link novo para uma sessão que não está mais ativa — concluída ou cancelada. Faz sentido: um link para uma sessão encerrada não autenticaria nada. Se a pessoa quer ver o que assinou, o caminho não é relinkar, é o download do documento ou a evidência.
Repetir a chamada resolve um 409?
Não. Ao contrário do 429 e do 503, o 409 é sobre estado, e o estado não muda porque você tentou de novo. Um mecanismo de nova tentativa automática que trate 409 como transitório vai repetir a mesma recusa até esgotar as tentativas.
Recebi 409 ao cancelar. O que houve?
Provavelmente a transação já está num estado terminal — concluída, cancelada ou expirada. Cancelar algo encerrado não é uma operação possível. Vale conferir o estado antes: se já está concluída, o que existe é um documento assinado, não algo a cancelar.
E 409 ao acrescentar um signatário?
Signatário repetido no mesmo envelope é recusado, assim como um índice de signatário já ocupado. Em fluxos que montam o envelope a partir de uma lista, a causa costuma ser duplicidade na origem — a mesma pessoa aparecendo duas vezes na planilha.
Como evito a maior parte dos 409?
Consultando o estado antes de agir. É uma leitura barata, e transforma um erro num ramo de decisão. Nos fluxos que reagem a eventos, vale lembrar que a ordem de chegada não é garantida: tratar um evento fora de ordem produz 409 previsíveis.
409 e 422 são parecidos?
São vizinhos e diferentes. O 422 diz que o conteúdo enviado não serve — documento corrompido, imagem sem rosto. O 409 diz que o conteúdo está bom e o objeto não está no estado que permite a operação. A correção do primeiro é mudar o que você envia; a do segundo é mudar quando você envia, ou o que você espera do objeto.
O 409 consome cota?
A recusa em si não cria transação nem envelope, então não há débito por causa dela. Mas atenção ao caso de recriar por engano: quem interpreta 409 como falha e cria um objeto novo do zero acaba consumindo um documento que não precisava — que é o dano mais comum associado a esse código.
Consulte o estado antes de agir
Quase todo 409 se evita com uma leitura barata antes da operação. Teste as transições no ambiente de homologação, que é gratuito e não pede cartão.
Criar credenciais de homologação Fale com o time comercial