Códigos de erro

Todo erro retorna o mesmo formato, com o status HTTP indicando a natureza do problema:

{
  "codigo": "DADOS_INVALIDOS",
  "descricao": "O campo numeroPne é obrigatório.",
  "detalhes": null
}

O campo detalhes só vem preenchido quando há informação adicional útil, como a lista de campos que falharam na desserialização.

Tabela de erros

HTTP	codigo	Quando acontece	O que fazer
400	DADOS_INVALIDOS	Campo obrigatório ausente, JSON malformado, tipo incompatível	Corrigir o payload e reenviar. Não adianta repetir a mesma requisição
401	NAO_AUTORIZADO	Token ausente, inválido, expirado, ou de uma conta que não é usuário de serviço	Obter novo token e repetir. Se persistir com token novo, conferir se a conta está marcada como usuário de serviço
404	NAO_ENCONTRADO	Referência informada não existe no Xjur	Verificar os dados enviados
409	CONFLITO	Conflito de estado no Xjur	Consultar o estado da pasta antes de reenviar
422	REGRA_NEGOCIO	O payload está bem formado, mas viola uma regra de negócio do Xjur	Rejeitar e registrar. Exige análise, não retentativa
502	ERRO_SERVICO_EXTERNO	O Xjur não respondeu ou respondeu de forma inesperada	Retentar, no máximo 3 vezes
504	TIMEOUT_SERVICO_EXTERNO	O Xjur ultrapassou o tempo limite	Retentar, no máximo 3 vezes

Sobre retentativa

Só vale retentar em 502 e 504, que são falhas de comunicação. Nesses casos a proposta pode ou não ter sido criada, e é justamente por isso que a retentativa é segura: reenviar a mesma proposta devolve a pasta existente em vez de criar outra.

400 e 422 não devem ser retentados. O primeiro é payload errado e o segundo é regra de negócio; repetir a mesma requisição produz o mesmo erro. Registre e trate.

Erros de validação mais comuns

Mensagem	Causa
O campo numeroPne é obrigatório.	Falta a identificação da proposta
O campo numeroPnePai é obrigatório quando isNovaPasta é 0.	Desdobramento sem informar a proposta de origem
O campo negociacoesList deve conter ao menos uma negociação.	Lista ausente ou vazia
O campo negociacoesList[0].docContabil é obrigatório.	Negociação sem documento contábil
O campo negociacoesList[0].partesContrariasList deve conter ao menos uma parte.	Negociação sem nenhuma parte
O campo negociacoesList[0].partesContrariasList[0].papelSignatarioId é obrigatório.	Parte sem papel definido

As mensagens apontam o caminho exato dentro do payload, incluindo o índice na lista, para localizar o problema sem precisar comparar o JSON inteiro.