Solução de problemas
Como diagnosticar
Verifique a disponibilidade
Chame GET /healthcheck. Se não houver resposta 200, o problema está na conectividade com o serviço.
Anote o status HTTP
Consulte o significado em Status HTTP.
Procure o sintoma
Veja os problemas comuns abaixo. Se o problema continuar, acione o suporte.
Dica
Use curl -i para ver o status e os headers da resposta. Antes de compartilhar a saída, remova tokens, cookies, senhas, PINs e links seguros.
Problemas comuns
Todas as chamadas retornam 403, inclusive com credenciais válidas
Sintoma: respostas 403 em rotas que deveriam funcionar.
Causa provável: o host ou a porta usados na URL não correspondem ao endereço configurado para o serviço (por exemplo, acesso por IP ou por um nome alternativo).
Solução: use exatamente o host informado pelo administrador do ambiente na URL base.
O token é válido, mas o upload ou o download é recusado
Sintoma: 403 em /upload, /download/list ou /report, com token aceito em outras rotas.
Causa provável: uma regra do usuário ou do ambiente impede a operação: serviço desabilitado, usuário bloqueado, horário não permitido, limite de tamanho, tipo ou nome de arquivo, ou limite de sessões simultâneas.
Solução: confira as regras de acesso com o administrador do serviço.
O login retorna 206 em vez de 200
Sintoma: /auth/login responde 206 Partial Content e não cria o cookie de sessão.
Causa provável: o usuário tem MFA habilitado.
Solução: conclua o segundo fator pelo linkURL recebido, como em Concluir o MFA.
O login funciona, mas não encontro o token no JSON
Sintoma: a resposta de /auth/login não tem campo com o token.
Causa provável: o login local entrega a sessão apenas no cookie __Host-dirl_session.
Solução: guarde e reenvie o cookie (curl -c e -b) ou obtenha um token Bearer pelo password grant.
O endpoint de token retorna 400
Sintoma: /auth/token ou /oauth2/token responde 400 com error e error_description.
Causa provável: corpo enviado em JSON em vez de formulário, campo obrigatório ausente, grant_type ou subject_token_type inválido, JWT de origem não aceito ou provedor não informado no token exchange.
Solução: envie application/x-www-form-urlencoded com os campos de Tokens OAuth e leia error_description.
Rotas protegidas retornam 401 depois de algum tempo
Sintoma: chamadas que funcionavam passam a responder 401.
Causa provável: o token ou a sessão expirou, ou a sessão foi encerrada.
Solução: obtenha uma nova credencial e repita a chamada. Veja Expiração.
O relatório retorna erro
Sintoma: GET /report responde com erro.
Causa provável: o parâmetro obrigatório filterdirection não foi enviado ou tem valor diferente de 5 (downloads concluídos) ou 7 (uploads concluídos).
Solução: inclua filterdirection. Veja Consultar relatórios.
O link de download, MFA ou senha não funciona (404 ou 400)
Sintoma: um linkURL ou link recebido por e-mail ou SMS retorna erro.
Causa provável: o link expirou, foi alterado (por exemplo, truncado ao copiar ou com a query string recodificada) ou o arquivo não está mais disponível.
Solução: use a URL integral, sem edição. Se tiver expirado, gere um novo link (nova listagem, novo login ou nova solicitação de senha).
O arquivo baixado está corrompido ou contém uma mensagem de erro
Sintoma: o arquivo salvo é pequeno demais ou contém texto em vez do conteúdo esperado.
Causa provável: a resposta de erro foi gravada como se fosse o arquivo, ou o conteúdo binário foi tratado como texto ou JSON.
Solução: verifique o status HTTP antes de salvar (curl --fail) e grave a resposta como binário.
O callback de SSO falha durante um teste
Sintoma: chamadas a /sso/oauth2/cb ou /sso/saml2/acs feitas manualmente são recusadas.
Causa provável: state, code e SAMLResponse são emitidos e assinados pelo provedor e vinculados à sessão do navegador.
Solução: teste o SSO pelo navegador, iniciando em /sso/login?provider=<nome>. Veja Single Sign-On.
O login, o primeiro acesso ou a recuperação de senha retorna 400, 403 ou 503
Sintoma: /auth/login, /auth/firstaccess ou /auth/forget falha antes de validar as credenciais.
Causa provável: o ambiente exige o Cloudflare Turnstile. 400: header CF-Turnstile-Response ausente ou inválido; 403: token rejeitado (inválido, expirado ou já utilizado); 503: a API não conseguiu validar o token com a Cloudflare.
Solução: gere um novo token do widget a cada tentativa e envie-o no header CF-Turnstile-Response. Em 503, tente novamente. Integrações sem navegador devem usar o password grant. Veja Cloudflare Turnstile.