Códigos de Erro

A API possui dois formatos de erro, conforme o endpoint consumido.

Para atualização de contratos, os erros retornam uma resposta JSON padronizada:

{
  "codigo": "CODIGO_DO_ERRO",
  "descricao": "Descrição legível do que ocorreu."
}

Atualização de contratos

HTTP	Código	Descrição	Causa
400	DADOS_INVALIDOS	O campo numeroContratoSap é obrigatório	Requisição enviada sem o campo obrigatório
404	CONTRATO_NAO_ENCONTRADO	Nenhum contrato foi encontrado para o número SAP informado	O numeroContratoSap não existe no sistema
502	ERRO_SERVICO_EXTERNO	Ocorreu um erro ao processar sua requisição	O Xjur APIM retornou erro ou está indisponível
504	TIMEOUT_SERVICO_EXTERNO	O serviço não respondeu a tempo	A chamada ao Xjur APIM excedeu o timeout configurado (10s)

Cadastro de partes contrárias

O endpoint POST /Contrato/AdicionarParteContraria retorna um contrato de resposta próprio para erros de negócio, contendo httpStatus, message, error e detalhes, quando aplicável.

{
  "httpStatus": 400,
  "error": "PAYLOAD_INVALIDO",
  "message": "Payload inválido.",
  "numeroPne": "PNE123456",
  "docContabil": "4500001234",
  "detalhes": "tipoRequisicao inválido ou não suportado."
}

HTTP	Código	Descrição	Causa
207	—	Resultados mistos	A requisição teve inclusões, duplicidades ou rejeições por registro
400	PAYLOAD_INVALIDO	Payload inválido	Campos obrigatórios ausentes, lista vazia, tipo não suportado ou duplicidade no payload
404	PNE_NAO_ENCONTRADA	Nenhum contrato encontrado	A combinação numeroPne + docContabil não foi localizada
409	REGISTROS_DUPLICADOS	Todos os registros já existem	Todas as pessoas enviadas já estavam vinculadas aos contratos encontrados
401	NAO_AUTORIZADO	Token inválido ou expirado	O Xjur rejeitou a autenticação repassada
502	ERRO_SERVICO_EXTERNO	Erro no serviço externo	O Xjur APIM retornou erro ou está indisponível
504	TIMEOUT_SERVICO_EXTERNO	Timeout no serviço externo	O Xjur APIM não respondeu dentro do tempo limite

Validação por registro

Quando o endpoint retorna 207, avalie o array registros. Cada item pode conter status, motivo e camposInvalidos.

Detalhes por código

DADOS_INVALIDOS — 400

O campo numeroContratoSap é obrigatório e não foi enviado na requisição.

{
  "codigo": "DADOS_INVALIDOS",
  "descricao": "O campo numeroContratoSap é obrigatório"
}

Como resolver: Inclua o campo numeroContratoSap no corpo da requisição.

---

CONTRATO_NAO_ENCONTRADO — 404

Não foi encontrado nenhum contrato com o número SAP informado na consulta ao Xjur APIM.

{
  "codigo": "CONTRATO_NAO_ENCONTRADO",
  "descricao": "Nenhum contrato foi encontrado para o número SAP informado."
}

Como resolver: Verifique se o valor de numeroContratoSap está correto e se o contrato existe no sistema Xjur.

---

ERRO_SERVICO_EXTERNO — 502

O Xjur APIM retornou uma resposta de erro (4xx ou 5xx) durante a consulta ou atualização do contrato.

{
  "codigo": "ERRO_SERVICO_EXTERNO",
  "descricao": "Ocorreu um erro ao processar sua requisição. Tente novamente em instantes."
}

Possíveis causas:

• Token JWT expirado ou sem permissão no APIM
• Contrato em estado que não permite atualização
• Serviço externo com instabilidade

Como resolver: Verifique o token JWT e tente novamente. Se persistir, entre em contato com o suporte Xjur.

---

TIMEOUT_SERVICO_EXTERNO — 504

A chamada ao Xjur APIM demorou mais do que o limite configurado (padrão: 10 segundos).

{
  "codigo": "TIMEOUT_SERVICO_EXTERNO",
  "descricao": "O serviço não respondeu a tempo. Tente novamente em instantes."
}

Como resolver: Tente novamente após alguns instantes. Se o timeout persistir com frequência, contate o suporte para ajustar o SLA configurado.

Idempotência e retries

Ao realizar retries em caso de timeout, o mecanismo de idempotência garante que enviar o mesmo payload não causará duplicidade de atualização caso a primeira chamada tenha sido processada com sucesso antes do timeout.

Detalhes — partes contrárias

PAYLOAD_INVALIDO — 400

O payload está ausente, incompleto, contém pessoasList vazia, possui tipoRequisicao não suportado ou contém pessoas duplicadas pelo mesmo cpfCnpj.

Como resolver: corrija os campos obrigatórios e envie apenas uma ocorrência por documento no mesmo payload.

---

PNE_NAO_ENCONTRADA — 404

Nenhum contrato foi encontrado para a combinação numeroPne + docContabil.

Como resolver: valide os dados de origem e confirme se o contrato já está cadastrado no Xjur.

---

REGISTROS_DUPLICADOS — 409

Todas as pessoas enviadas já estavam vinculadas aos contratos encontrados.

Como resolver: trate como operação sem nova inclusão. Caso esperado, não reenvie o mesmo conjunto de pessoas.

---

Resultados mistos — 207

A requisição foi processada, mas nem todos os registros resultaram em nova inclusão.

Como resolver: avalie o array registros e use motivo e camposInvalidos para corrigir apenas os itens rejeitados.

Exemplos de tratamento em código

C#

var response = await client.PutAsJsonAsync("/contratos", payload);

if (!response.IsSuccessStatusCode)
{
    var erro = await response.Content.ReadFromJsonAsync<ErrorResponse>();
    var acao = erro?.Codigo switch
    {
        "DADOS_INVALIDOS"          => "Verifique os dados enviados.",
        "CONTRATO_NAO_ENCONTRADO"  => "Número SAP inválido ou contrato inexistente.",
        "TIMEOUT_SERVICO_EXTERNO"  => "Tente novamente em instantes.",
        "ERRO_SERVICO_EXTERNO"     => "Contate o suporte Xjur.",
        _                          => "Erro desconhecido."
    };
    Console.WriteLine($"[{erro?.Codigo}] {acao}");
}

JavaScript/TypeScript

const res = await fetch('/contratos', { method: 'PUT', ... });

if (!res.ok) {
  const erro = await res.json();
  const mensagens = {
    DADOS_INVALIDOS:          'Verifique os campos obrigatórios.',
    CONTRATO_NAO_ENCONTRADO:  'Número SAP não encontrado.',
    TIMEOUT_SERVICO_EXTERNO:  'Serviço temporariamente indisponível.',
    ERRO_SERVICO_EXTERNO:     'Erro interno — contate o suporte.',
  };
  console.error(mensagens[erro.codigo] ?? 'Erro desconhecido.');
}