Pular para o conteúdo
Integrações Inteligentes

Erros Comuns

Guia de troubleshooting para problemas comuns na plataforma.

Autenticação

Token inválido ou expirado

Erro: 401 Unauthorized

Causas:

  • Token incorreto ou digitado errado
  • Token WEB expirou (30 dias)
  • Token foi revogado

Solução:

  1. Verifique se está usando o token correto
  2. Gere um novo token no Dashboard

Não autorizado para este recurso

Erro: 403 Forbidden

Causas:

  • Tentando acessar instalação de outro tenant
  • Permissões insuficientes

Solução: Verifique se o ID da instalação pertence ao seu tenant.

Webhooks

Não recebo events

Verificações:

  1. Webhook URL configurada?

    Terminal window
    GET /me/tenant

    Verifique se webhook_url está preenchido.

  2. Events habilitados?

    Terminal window
    GET /installations/{id}

    Verifique enabled_events.

  3. URL válida?

    Terminal window
    PUT /me/tenant/webhook_url

    Veja se passa na validação.

  4. Webhook configurado na plataforma externa? Verifique se configurou a URL de ingestion no provedor.

Timeout ao validar webhook

Erro: O webhook não respondeu dentro do tempo limite.

Causas:

  • Servidor lento
  • Processamento síncrono demorado

Solução: Responda imediatamente com HTTP 200, processe assincronamente.

Gzip não suportado

Erro: O endpoint não aceita gzip.

Solução: Implemente descompressão gzip no seu servidor.

Instalações

Driver não possui configuração

Erro: O driver selecionado não possui configuração.

Solução: Configure o driver antes de criar a instalação:

Terminal window
PUT /drivers/{id}/settings

Evento inválido

Erro: O evento selecionado é inválido.

Causa: Tentando habilitar evento que não existe no driver.

Solução: Liste events disponíveis:

Terminal window
GET /drivers/{id}

Verifique available_settings.

Setup OAuth incompleto

Erro: needs_setup: true

Solução: Siga o fluxo OAuth:

  1. Redirecione para oauth_authorization_url
  2. Usuário autoriza
  3. Callback completa automaticamente

Veja Setup OAuth.

Events

Event falhou todas as tentativas

Status: failed

Causas:

  • Seu servidor retornou erro 5xx
  • Seu servidor não respondeu em 10s
  • Sua URL foi removida

Solução:

  1. Corrija o problema no seu servidor
  2. Reenvie o evento:
    Terminal window
    POST /processing/events/{id}/resend

Events duplicados

Comportamento: Mesmo evento recebido múltiplas vezes.

Causa: Normal em caso de falhas. A plataforma re-tenta automaticamente.

Solução: Implemente idempotência usando o campo id:

if (processedEvents.has(event.id)) {
  return; // Já processado
}

API

Rate Limiting

Erro: 429 Too Many Requests

Causa: Muitas requisições em pouco tempo.

Solução:

  • Implemente backoff exponencial
  • Use caching para dados que não mudam frequentemente
  • Distribua carga ao longo do tempo

JSON inválido

Erro: 422 Unprocessable Entity

Causas:

  • Body não é JSON válido
  • Content-Type incorreto

Solução:

Terminal window
curl -X POST ... \
  -H "Content-Type: application/json" \
  -d '{"campo": "valor"}'

Campo obrigatório ausente

Erro: 422 Unprocessable Entity com detalhes

Solução: Verifique a documentação do endpoint e inclua todos os campos obrigatórios.

Drivers

Driver não encontrado

Erro: 404 Not Found

Causas:

  • ID do driver incorreto
  • Driver desabilitado

Solução: Liste drivers disponíveis:

Terminal window
GET /drivers

Processing

Webhook não processado

Status: queued, processing ou failed

Verificações:

  1. Status atual:

    Terminal window
    GET /processing/ingestion/{id}

  2. Histórico: Verifique status_history na resposta.

  3. Erro específico: Veja status_reason para detalhes.

Event não foi gerado

Causas:

  • Webhook não foi recebido
  • Falhou no processamento
  • Event não mapeado

Verificações:

  1. Veja se webhook foi recebido:

    Terminal window
    GET /processing/ingestion

  2. Verifique eventos suportados do driver

  3. Veja logs de processamento

SSL/TLS

Erro de certificado

Erro: SSL certificate problem

Causas:

  • Certificado expirado
  • Certificado auto-assinado
  • Chain incompleta

Solução: Use certificados válidos de autoridades reconhecidas (Let’s Encrypt, etc.).

DNS

Host não encontrado

Erro: Could not resolve host

Causas:

  • URL incorreta
  • DNS não propagado

Solução: Verifique a URL e aguarde propagação de DNS (até 48h).

Suporte

Se o problema persistir:

  1. Colete informações:

    • ID do event/installation
    • Timestamp
    • Código de erro
    • Logs

  2. Entre em contato via:

Checklist de Diagnóstico

Terminal window
# 1. Verificar autenticação
GET /me


# 2. Verificar tenant
GET /me/tenant


# 3. Listar drivers
GET /drivers


# 4. Verificar installation
GET /installations/{id}


# 5. Verificar webhooks recebidos
GET /processing/ingestion


# 6. Verificar events
GET /processing/events


# 7. Verificar tentativas
GET /processing/dispatches

Próximos Passos