Integração Corporativa

Códigos de erro

Toda resposta de erro inclui error_code estável (machine-readable) e message em português pronta para exibir ao usuário final. Use error_code na sua lógica, nunca o message.

Formato padrão

JSON

{
  "statusCode": 403,
  "error_code": "CONTRACT_INACTIVE",
  "message": "Seu plano está temporariamente indisponível. Entre em contato com sua seguradora.",
  "request_id": "req_4f2a..."
}

Tabela completa

error_code	HTTP	Categoria	Significado	Ação sugerida
INVALID_API_KEY	401	Autenticação	API Key ausente, inválida ou revogada.	Verifique o header X-API-Key. Gere uma nova chave se necessário.
INVALID_TOKEN	401	Autenticação	JWT inválido, expirado ou malformado.	Faça login novamente para obter um novo access_token.
FORBIDDEN	403	Autenticação	Token válido mas sem permissão para o recurso.	Confirme que o usuário possui corporateContext ou que a API Key tem o escopo necessário.
CONTRACT_INACTIVE	403	Elegibilidade	Contrato corporativo inativo, suspenso ou expirado.	Entre em contato com o gerente de conta NetGuincho.
USER_NOT_FOUND	404	Elegibilidade	CPF não vinculado ao contrato.	Cadastre o segurado via POST /insurer-portal/customers.
USER_INACTIVE	403	Elegibilidade	Segurado existe mas está desativado.	Reative via PATCH /insurer-portal/customers/:id com status=active.
LIMIT_EXCEEDED	429	Elegibilidade	Limite mensal de acionamentos atingido para este segurado.	Aumente monthly_limit ou aguarde o próximo mês.
OPEN_REQUEST_EXISTS	409	Solicitação	Já existe um chamado em andamento para o segurado.	Conclua ou cancele o chamado anterior antes de criar outro. ID retornado em open_request_id.
VALIDATION_ERROR	422	Solicitação	Payload inválido (campo faltando, tipo incorreto, valor fora do range).	Veja a mensagem detalhada em "message" para o campo específico.
NO_PROVIDER_AVAILABLE	503	Solicitação	Nenhum prestador disponível na região no momento.	Aguarde alguns minutos e tente novamente. NetGuincho expande raio automaticamente após 5 min.
RATE_LIMITED	429	Rate limit	Excedeu o limite de requisições por minuto.	Respeite o header Retry-After. Considere implementar backoff exponencial.
INTERNAL_ERROR	500	Servidor	Erro interno inesperado.	Reportar ao suporte com o request_id retornado para investigação.
SERVICE_UNAVAILABLE	503	Servidor	API temporariamente indisponível (manutenção, degradação).	Tente novamente após alguns segundos. Veja status.netguincho.com.br para incidentes ativos.

Tratamento recomendado

TypeScript

async function callEligibility(cpf: string) {
  try {
    const { data } = await api.post('/insurer-portal/eligibility/check', { cpf });
    return data;
  } catch (err) {
    if (!axios.isAxiosError(err) || !err.response) throw err;
    const { error_code, message } = err.response.data;

    switch (error_code) {
      case 'LIMIT_EXCEEDED':
        return { blocked: true, reason: 'limite mensal atingido', message };
      case 'USER_NOT_FOUND':
        return { blocked: true, reason: 'segurado não cadastrado', message };
      case 'CONTRACT_INACTIVE':
        // Alerta crítico interno
        notifyOps('Contrato NetGuincho inativo!');
        return { blocked: true, reason: 'contrato', message };
      case 'RATE_LIMITED':
        await sleep(parseInt(err.response.headers['retry-after'] ?? '60') * 1000);
        return callEligibility(cpf);
      default:
        throw err;
    }
  }
}