Erro 422: documento recusado e recurso não habilitado
O 422 é o código mais mal interpretado da API, porque ele não significa que algo deu errado no caminho — significa que o dado chegou, foi analisado e foi recusado. Isso muda a conduta: repetir a mesma chamada não resolve, e um mecanismo de nova tentativa automática só vai repetir a recusa. Na prática existem duas famílias com causas opostas: o documento que você enviou não serve, ou o recurso que você chamou existe mas não está habilitado para a sua conta. A primeira se corrige no seu lado; a segunda, não.
A regra de conduta: 422 é determinístico. O dado chegou, foi analisado e foi recusado — repetir a mesma chamada produz a mesma resposta. Trate como erro terminal daquela tentativa, nunca como candidato a nova tentativa automática.
Duas famílias, causas opostas
| Conteúdo recusado | Recurso não habilitado | |
|---|---|---|
| A mensagem fala de | O documento ou a imagem | Um recurso e o tenant |
| Exemplo | No face detected in image |
… is not enabled for this tenant |
| De quem é a correção | Sua — corrigir o arquivo | Provisionamento — falar com o comercial |
| Reenviar corrigido resolve? | Sim | Não. Nada que você envie muda isso |
Distinguir as duas em um olhar economiza horas: metade dos chamados sobre 422 são de gente tentando consertar no código algo que é uma configuração de conta.
Família 1: o documento não serve
O documento passa por validação antes de ser aceito — tanto no envio inline quanto na confirmação do upload por URL pré-assinada. As causas típicas:
- PDF protegido por senha. A mais comum e a mais fácil de não enxergar: o arquivo abre normalmente na máquina de quem enviou, porque a senha bloqueia manipulação, não leitura. Contratos exportados de sistemas jurídicos frequentemente vêm assim.
- PDF corrompido ou truncado. Típico de upload interrompido ou de arquivo remontado de pedaços.
- Fora dos critérios mínimos de qualidade. O detalhe vem no corpo.
- Documento ausente na hora errada —
Document must be uploaded before signingou… before finalization. Não é o arquivo: é a ordem das operações.
Quando o fluxo envolve imagem, a mesma família traz mensagens próprias e bastante literais:
A segunda pega mais gente do que se imagina: a foto tem o titular e alguém ao fundo. O requisito é exatamente um rosto detectável — nem zero, nem dois.
Família 2: o recurso não está habilitado
Estas terminam sempre da mesma forma, e a mensagem é honesta sobre o que está acontecendo:
Aqui não há nada a corrigir no código. O recurso existe na API, a sua chamada está bem formada, e ele simplesmente não está provisionado para a sua conta. É uma conversa com o time comercial, não uma sessão de depuração.
Vale reconhecer o padrão porque ele aparece cedo: alguém lê sobre uma capacidade na documentação, implementa, e recebe 422 na primeira execução. O código está certo desde o começo.
O 422 que aparece no meio de uma assinatura
Há um caso que merece atenção separada porque acontece com o signatário na tela: a comparação facial não encontra a referência do usuário. A mensagem cita ausência de imagem de referência ou de cadastro.
A causa costuma ser prazo, não erro: a imagem de referência tem vida limitada, e depois disso a comparação passa a falhar até haver novo cadastro. É por isso que uma varredura periódica de cadastros vencidos vale a pena — ela transforma essa falha, que hoje aparece na frente do signatário, num aviso interno tratável com antecedência.
Cota: o detalhe de momento que surpreende
A cota de documento é debitada quando a transação ou o envelope é criado, não quando o documento é aceito. Um 422 no upload acontece depois desse débito — ou seja, um PDF protegido por senha pode custar um documento do plano antes de ser recusado.
Por isso vale validar o arquivo do seu lado antes de criar a transação: abrir o PDF, verificar que não está cifrado e que tem as páginas esperadas. É barato, e evita a combinação mais irritante — cota gasta e assinatura não enviada.
422 não é 400, nem 413, nem 429
| Código | Significa | Repetir resolve? |
|---|---|---|
400 |
A requisição está malformada — campo faltando, formato inválido | Não |
413 |
O corpo é grande demais | Não — mude o método de envio |
422 |
O conteúdo chegou e não serve | Não |
429 |
Limite de requisições ou de tentativas | Sim, respeitando o intervalo |
503 |
Indisponível no momento | Sim, com espera |
O 413 merece nota porque é confundido com o 422 quando o documento é grande: ele não diz que o arquivo é ruim, diz que ele não cabe no corpo da requisição. A saída não é comprimir e tentar de novo — é trocar para o envio por URL pré-assinada, descrito em upload de documentos grandes. Lembre que base64 infla o payload em cerca de um terço.
O que fazer no código
- Não repita automaticamente. Se o seu wrapper de nova tentativa trata qualquer erro como transitório, 422 vira um laço que só gasta requisições.
- Leia o detalhe da resposta e registre-o. Um log que guarda só "422" não permite distinguir as duas famílias depois.
- Ramifique pela família. Mensagem terminando em not enabled for this tenant não é bug: encaminhe, não tente consertar.
- Valide o arquivo antes de criar a transação, pela razão de cota acima.
- Mostre ao usuário o que ele pode consertar. "Este PDF está protegido por senha" é acionável; "erro ao enviar documento" não é.
Para o catálogo completo dos códigos, veja códigos de erro e tratamento de falhas, e para as armadilhas de primeira integração, os 12 erros mais comuns. O painel traz a explicação de cada erro ao lado da requisição real, como descrito em o painel de API. E a visão geral da API de assinatura digital descreve os recursos citados aqui.
Perguntas Frequentes
O que 422 significa nessa API?
Que a requisição foi recebida e entendida, mas o conteúdo não pôde ser processado. Não é erro de rede, de autenticação nem de formato do JSON — esses têm códigos próprios. É o servidor dizendo "chegou, analisei e não serve".
Devo repetir a chamada?
Não. Um 422 é determinístico: a mesma entrada produz a mesma recusa. Repetição automática só consome o seu limite de requisições. Trate 422 como erro terminal daquela tentativa e escale para correção — ao contrário do 429 e do 503, que pedem nova tentativa.
Meu PDF foi recusado. Quais são as causas?
PDF corrompido, protegido por senha, ou fora dos critérios mínimos de qualidade. O detalhe vem no corpo da resposta. Protegido por senha é a causa mais comum e a mais fácil de perder de vista, porque o arquivo abre normalmente na máquina de quem o enviou — a senha só bloqueia a manipulação programática.
O que significa "não habilitado para este tenant"?
Que o recurso existe na API e não está provisionado para a sua conta. Aparece em capacidades como captura hospedada de vivacidade, extração de rosto de documento, políticas customizadas e imagem de referência por transação. Não é um erro de código: é provisionamento, e a correção é falar com o comercial.
Como distingo as duas famílias rapidamente?
Pela mensagem. Se ela descreve o documento ou a imagem — corrompido, sem rosto, múltiplos rostos, com senha — é a família de conteúdo e a correção é sua. Se ela termina em "is not enabled for this tenant", é provisionamento.
Recebo 422 dizendo que o documento precisa ser enviado antes. O que é?
Ordem de operações: a transação foi criada mas o documento ainda não foi anexado, e você chamou finalização ou assinatura. A correção é enviar o documento antes — inline em base64 para arquivos pequenos, ou pelo fluxo de URL pré-assinada para os maiores.
Um 422 consome cota?
A recusa em si não é uma assinatura, mas atenção ao momento: a cota de documento é debitada quando a transação ou o envelope é criado, não quando o documento é aceito. Um 422 no upload acontece depois desse débito — por isso vale validar o arquivo do seu lado antes de criar a transação.
Distinga o que é seu do que é provisionamento
Documento recusado se conserta no seu lado; recurso não habilitado é conversa com o time comercial. As credenciais de homologação são gratuitas e mostram os dois casos.
Criar credenciais de homologação Fale com o time comercial