Pular para conteúdo

Erros Comuns - ecosif-compliance

Este documento lista os erros mais comuns ao integrar com a API ecosif-compliance e como resolvê-los.

Erros de autenticação

401 Unauthorized — "Invalid Token"

Problema: token ausente, malformado, expirado ou assinatura inválida.

Soluções:

  1. Inclua Authorization: Bearer <token> (com o prefixo Bearer)
  2. Faça login novamente no ecosif-auth
  3. Confira se AUTH_TOKEN_SECRET é a mesma do ecosif-auth (modos ECOSIF_JWT / híbrido)
  4. No modo Azure/Google, confira tenant, audiência e JWKS

Erros de validação

400 Bad Request

Problema: dados de entrada inválidos.

Exemplos:

  • refmonth fora de YYYY-MM
  • since no path de processos fora de YYYY-MM-DD
  • nome de regra vazio ou já existente
  • filtro de empresa com menos de 3 caracteres em /company/list/{name}
  • documents não é um JSON array válido

Solução: confira os campos obrigatórios na lista de endpoints.

403 Forbidden

Problema: usuário autenticado sem acesso à empresa/filial do recurso.

Solução: use uma empresa/filial vinculada ao usuário (mesmo critério do masterdata).

Erros de execução

500 Internal Server Error

Problema: falha interna (banco, DSL, dados inconsistentes).

Soluções:

  1. Verifique logs do serviço
  2. Confirme que saldos/documentos existem no banco
  3. Teste o script em POST /api/compliance/test antes de persistir a regra

Erro de script DSL

Problema: script inválido ou função inexistente.

Soluções:

  • Use /api/compliance/test
  • Funções: SALDO_CONTA, SOMA_SALDO_CONTAS, VARIACAO_SALDO, DIFERENCA_PERCENTUAL_SALDOS
  • Comandos: IF / THEN / ELSE, RETORNA, ERRO

Swagger / OpenAPI indisponível

Problema: /docs/ ou /v3/api-docs retornam 401 ou 404.

Solução: ECOSIF_COMPLIANCE_SWAGGER_ENABLED=true em desenvolvimento. Em produção o padrão recomendado é desligar a UI.

Próximos passos