Códigos de Erro

Todos os erros da API retornam uma resposta JSON padronizada:

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

Tabela de erros

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)

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.

Exemplos de tratamento em código

C#

var response = await client.PutAsJsonAsync("/sap/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('/sap/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.');
}