Solucao De Problemas - Escavador Business API - Documentação

Como usar este guia

Para cada incidente:

1. Identifique o sintoma principal (status HTTP e mensagem).
2. Rode o diagnóstico sugerido da seção correspondente.
3. Aplique a correção e valide com um payload mínimo.
4. Se persistir, escale com evidências usando o template ao final.

Navegação rápida por sintoma

• Se o erro é 401: vá para Autenticação inválida.
• Se o erro é 429: vá para Rate limit.
• Se o erro é 4xx de validação: vá para Payload e filtros.
• Se o erro é 5xx: vá para Falhas transitórias.
• Se o problema é callback/webhook: vá para Entrega de webhooks.
• Se o problema é resultado inconsistente: vá para Paginação e dados.

Checklist de triagem (2 minutos)

Este checklist evita os erros mais comuns de configuração e costuma resolver boa parte dos incidentes sem investigação profunda.

• Confirmar URL base e ambiente (homologação/produção).
• Confirmar token Bearer válido e não revogado.
• Confirmar status HTTP, endpoint e horário do erro.
• Reproduzir com payload mínimo.
• Verificar limite de taxa e saldo de créditos.

Exemplo base de chamada autenticada

Use este exemplo como referência para testar conectividade e autenticação fora da sua aplicação.

curl -X GET "https://api.escavador.com/api/v1/quantidade-creditos" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer SEU_TOKEN"

Fluxo de diagnóstico recomendado

1. Validar autenticação e ambiente.
2. Validar payload/filtros e contrato esperado.
3. Verificar limite de taxa e créditos.
4. Repetir com payload mínimo.
5. Correlacionar logs de request/response.
6. Escalar com evidências (status, mensagem, horário e payload mascarado).

Autenticação inválida (401)

Quando você recebe 401, o problema normalmente está em credencial, formatação do header ou troca de ambiente. A correção quase sempre vem de padronização do cliente HTTP.

Diagnóstico:

• Header Authorization ausente ou mal formatado.
• Token expirado/revogado.
• Token de ambiente diferente da URL usada.

Correção:

• Padronize o cliente para sempre enviar Authorization: Bearer <token>.
• Separe tokens por ambiente.
• Em caso de dúvida, gere novo token e teste com payload mínimo.

Exemplo de validação em JavaScript

const res = await fetch(
  "https://api.escavador.com/api/v1/quantidade-creditos",
  {
    headers: {
      Accept: "application/json",
      Authorization: `Bearer ${process.env.ESCAVADOR_TOKEN}`,
    },
  }
);

if (res.status === 401) {
  throw new Error("Token inválido/expirado ou ambiente incorreto");
}

Erro de créditos insuficientes

Esse cenário é comum em operações de lote, especialmente quando há aumento de volume ou repetição de chamadas por timeout/retry mal calibrado.

Diagnóstico:

• Validar saldo disponível antes do processamento.
• Comparar custo estimado do lote com o saldo atual.
• Identificar chamadas duplicadas no fluxo.

Correção:

• Colocar guarda de saldo antes de iniciar lotes.
• Reduzir chamadas redundantes com cache e deduplicação.
• Ajustar estratégia de consumo por rota.

Exemplo de guarda antes de lote

if (saldoAtual <= custoEstimadoDoLote) {
  throw new Error("Saldo insuficiente para executar o lote com segurança");
}

Rate limit (429 Too Many Requests)

429 indica excesso de concorrência ou rajadas de requisição em uma janela curta. A solução mais eficaz é combinar limitação de concorrência com retry exponencial e jitter.

Diagnóstico:

• Medir taxa real de requisições por segundo/minuto.
• Verificar número de workers executando em paralelo.
• Confirmar se há retries simultâneos sem backoff.

Correção:

• Aplicar retry exponencial com jitter.
• Limitar concorrência por chave de cliente.
• Distribuir lotes em janelas menores.

Exemplo de retry exponencial com jitter

async function withRetry(fn, max = 5) {
  for (let tentativa = 0; tentativa < max; tentativa++) {
    try {
      return await fn();
    } catch (err) {
      const status = err?.status ?? err?.response?.status;
      if (status !== 429 && status < 500) throw err;
      const base = 200 * 2 ** tentativa;
      const jitter = Math.floor(Math.random() * 150);
      await new Promise((r) => setTimeout(r, base + jitter));
    }
  }
  throw new Error("Limite de tentativas excedido");
}

Entrega de webhooks

Webhook não recebido

Se o evento não chega, o problema geralmente está em rede, TLS ou tempo de resposta do seu endpoint.

Diagnóstico:

• Confirmar que o endpoint está público e acessível externamente.
• Validar certificado TLS e cadeia completa.
• Verificar se a resposta está retornando 2xx rapidamente.

Correção:

• Retornar ACK rápido e processar de forma assíncrona.
• Corrigir SSL/rota pública.
• Monitorar taxa de erro e latência no receptor.

Webhook duplicado

Duplicidade costuma acontecer por reentrega após timeout/falha transitória. Por isso, o consumo precisa ser idempotente.

Use o campo uuid do payload como chave de idempotência: ele é preservado nas reentregas do mesmo aviso. No exemplo, event_id é a coluna local que armazena esse UUID.

CREATE UNIQUE INDEX idx_webhook_evento_unico
ON webhooks_recebidos (event_id);

// Pseudocódigo: a inserção e os efeitos locais usam a mesma transação.
await banco.transaction(async (transacao) => {
  // Inserção atômica pela chave única; retorna false apenas se já existe.
  const novo = await registrarEventoSeAusente(transacao, payload.uuid);
  if (!novo) return;

  await processarEventoLocal(transacao, payload);
});
return ok();

Se o processamento falhar, a transação deve reverter também o registro do evento, permitindo nova tentativa. Responda com sucesso somente após o commit. Para processamento demorado ou efeitos externos, persista o evento em uma fila durável antes de confirmar o recebimento; o consumidor precisa controlar tentativas e idempotência desses efeitos. Uma transação local não desfaz chamadas externas.

Paginação e dados

Paginação interpretada incorretamente

Quando só a primeira página funciona, normalmente o cliente está montando URL manualmente ou ignorando metadados de paginação.

Diagnóstico:

• Conferir items, links e paginator da resposta da rota usada no exemplo.
• Garantir que o loop usa next devolvido pela API.
• Validar se filtros/ordenação mudam entre páginas.

Correção:

• Ler paginação a partir da própria resposta.
• Não assumir tamanho fixo de página.
• Tratar resultados como fluxo incremental.

Exemplo de loop seguro de paginação

let nextUrl = "https://api.escavador.com/api/v1/monitoramentos-tribunal?page=1";

while (nextUrl) {
  const res = await fetch(nextUrl, {
    headers: { Authorization: `Bearer ${token}` },
  });
  if (!res.ok) throw new Error(`Falha ao consultar página: HTTP ${res.status}`);
  const body = await res.json();
  if (!Array.isArray(body.items)) throw new Error("Resposta sem a lista items esperada");

  for (const item of body.items) {
    await processar(item);
  }

  nextUrl = body?.links?.next ?? null;
}

Filtro de data com resultado inesperado

Esse tipo de divergência é comum por timezone, formato de data ou intervalos muito amplos.

• Normalize timezone no cliente.
• Envie datas no formato aceito pela rota.
• Reproduza com intervalo curto e conhecido.

Campos ausentes, nulos ou com nome diferente

Em integrações robustas, o parser deve assumir que alguns campos são opcionais.

• Trate campos opcionais com fallback.
• Evite parser rígido acoplado à ordem do JSON.

Falhas transitórias (5xx)

5xx tende a representar indisponibilidade temporária, latência alta de dependências ou timeout em cadeia. O objetivo é resiliência sem amplificar o problema.

Diagnóstico:

• Verificar janela de ocorrência e volume.
• Comparar taxa de falha por endpoint.
• Confirmar se o erro é persistente ou intermitente.

Correção:

• Definir timeout por operação.
• Aplicar retry seletivo para erros transitórios.
• Usar circuit breaker no consumidor.

Diferença entre homologação e produção

Boa parte dos incidentes de go-live acontece por divergência de configuração entre ambientes.

Checklist:

• URL base correta.
• Credenciais do ambiente correto.
• Liberação de rede/IP.
• Smoke test pós deploy.

CORS em integração browser

Para rotas sensíveis, prefira integração server-to-server. Quando a chamada precisa partir do navegador, configure CORS explicitamente e com princípio do menor privilégio.

Diagnóstico:

• Inspecionar requisição OPTIONS (preflight).
• Verificar headers de resposta (Access-Control-Allow-*).

Correção:

• Restringir origens permitidas.
• Declarar métodos/headers estritamente necessários.
• Evitar * em cenários autenticados.

Catálogo rápido por status

• 2xx: sucesso, seguir fluxo normal.
• 4xx: ajustar autenticação/payload/limites.
• 5xx: tratar como transitório com observabilidade e retry controlado.

Modelo para escalar incidente

Use este template ao acionar suporte interno:

Endpoint: <rota>
Status HTTP: <codigo>
Horário: <YYYY-MM-DD HH:mm:ss TZ>
Request ID/Correlation ID: <id>
Payload mascarado: <json>
Tentativas realizadas: <n>
Impacto: <descricao>