Códigos de Erro

Todos os erros dos endpoints /xsigner/* seguem o formato padrão do XJUR Connect:

{
  "codigo": "CODIGO_DO_ERRO",
  "descricao": "Descrição legível do que ocorreu.",
  "detalhes": "Mensagem original do Xjur, quando disponível."
}

detalhes só aparece quando o Xjur devolveu uma mensagem útil para o integrador.

Tabela de erros

HTTP	Código	Quando ocorre
400	DADOS_INVALIDOS	Validação do payload no XJUR Connect (campo obrigatório ausente, extensão não aceita, e-mail repetido, base64 inválido, papel inexistente) ou regra de negócio rejeitada pelo Xjur (envelope já assinado, signatário já assinou)
401	NAO_AUTORIZADO	Token ausente, inválido ou expirado
403	SEM_PERMISSAO	O usuário de serviço não está habilitado para o XSigner
404	NAO_ENCONTRADO	Envelope ou signatário não localizado para o cliente do token
409	CONFLITO	O Xjur rejeitou a operação por conflito de estado
413	—	Corpo da requisição acima do limite (documentos em base64 muito grandes)
502	ERRO_SERVICO_EXTERNO	O Xjur respondeu com erro interno ou está indisponível. detalhes traz a mensagem do Xjur quando houver
504	TIMEOUT_SERVICO_EXTERNO	O Xjur não respondeu dentro do tempo limite

Mensagens mais comuns

Validação do payload (400)

Descrição	Como resolver
O campo assunto é obrigatório.	Informe assunto (até 100 caracteres)
Informe ao menos um documento em documentos.	Envie ao menos um item em documentos
documentos[0]: extensão ".xlsx" não aceita. Utilize .pdf, .doc, .docx.	Converta o arquivo para PDF ou Word
documentos[0]: informe documentoId (documento já existente no Xjur) ou nomeArquivo + conteudoBase64.	Cada documento precisa de uma das duas formas
conteudoBase64 do arquivo "contrato.pdf" não é um base64 válido.	Codifique o arquivo em base64 padrão (com ou sem prefixo data URI)
O arquivo "contrato.pdf" excede o tamanho máximo de 25 MB.	Reduza o arquivo
O arquivo "contrato.pdf" está corrompido ou fora do padrão PDF e não poderia ser assinado (...)	O arquivo abre em visualizadores tolerantes, mas não passa na validação estrutural usada na assinatura (tabela xref, startxref, Length dos streams). Gere o PDF com uma ferramenta padrão (Word, navegador ou biblioteca de PDF) em vez de montá-lo manualmente
O arquivo "contrato.pdf" não é um PDF: o conteúdo não começa com o cabeçalho %PDF-.	Confira se o conteúdo enviado é o arquivo em si (e não o base64 codificado duas vezes, por exemplo)
Envie o arquivo no campo "arquivo" (multipart/form-data).	No POST /xsigner/documentos, envie o arquivo no campo arquivo com Content-Type: multipart/form-data
arquivo: extensão ".txt" não aceita. Utilize .pdf, .doc, .docx.	Converta o arquivo para PDF ou Word
signatarios[1].nome deve conter nome e sobrenome.	Informe o nome completo
signatarios[1].email é obrigatório: o XSigner envia o link de assinatura por e-mail.	Informe um e-mail válido
E-mail repetido entre os signatários: ...	Cada e-mail só pode aparecer uma vez no envelope
signatarios[0].papelSignatarioId ou signatarios[0].papel é obrigatório.	Informe o papel (veja GET /xsigner/papeis-signatario)
Papel de signatário "Fiador" não encontrado.	Use um dos nomes retornados por GET /xsigner/papeis-signatario ou cadastre o papel no Xjur
Com enviarPorOrdem = true, cada signatário precisa ter uma ordem distinta.	Ajuste o campo ordem
Status "Pendente" inválido. Valores aceitos: Cancelado, EmConfeccao, AguardandoSignatarios, Assinado.	Use os nomes ou códigos do domínio

Regras de negócio do Xjur (400)

Descrição	Como resolver
Envelope 1532 já foi assinado e não pode ser cancelado.	Envelopes concluídos são imutáveis
Envelope 1532 já está cancelado.	Nenhuma ação necessária
O signatário 4101 está com status Assinado e não pode ser alterado.	Só signatários pendentes podem ser alterados, removidos ou receber reenvio
O envelope 1532 ainda não foi assinado por todos os signatários (status atual: AguardandoSignatarios).	Aguarde status = Assinado antes de baixar o documento assinado
Este email ... já está na lista de signatários.	O e-mail já pertence a um signatário pendente do envelope
Não é possível adicionar um signatário em uma posição igual ou anterior a um signatário que já assinou.	Informe uma ordem maior que a dos signatários que já assinaram

Não encontrado (404)

Descrição	Como resolver
Envelope 1532 não encontrado.	Confira o envelopeId; envelopes de outros clientes não são visíveis
Signatário 99 não encontrado no envelope 1532.	Confira o signatarioId na resposta do envelope

Exemplo de tratamento

try:
    envelope = criar_envelope("PEDIDO-2026-000123", "contrato.pdf")
except requests.HTTPError as e:
    body = e.response.json()
    codigo, descricao = body.get("codigo"), body.get("descricao", "")

    if codigo == "DADOS_INVALIDOS":
        print("Corrija o payload:", descricao)
    elif codigo == "NAO_ENCONTRADO":
        print("Envelope ou signatário não localizado:", descricao)
    elif codigo in ("ERRO_SERVICO_EXTERNO", "TIMEOUT_SERVICO_EXTERNO"):
        print("Instabilidade no Xjur, tente novamente:", body.get("detalhes"))
    else:
        raise

Retentativas

A criação de envelope não é idempotente: em caso de 504, consulte GET /xsigner/envelopes?codigo=<seu-codigo> antes de reenviar, para não criar envelopes duplicados.