Solución de problemas
Cómo diagnosticar
Verifique la disponibilidad
Llame a GET /healthcheck. Si no hay una respuesta 200, el problema está en la conectividad con el servicio.
Anote el estado HTTP
Consulte su significado en Estados HTTP.
Busque el síntoma
Consulte los problemas comunes a continuación. Si el problema persiste, contacte al soporte.
Consejo
Use curl -i para ver el estado y las cabeceras de la respuesta. Antes de compartir la salida, elimine tokens, cookies, contraseñas, PIN y enlaces seguros.
Problemas comunes
Todas las llamadas devuelven 403, incluso con credenciales válidas
Síntoma: respuestas 403 en rutas que deberían funcionar.
Causa probable: el host o el puerto usados en la URL no corresponden a la dirección configurada para el servicio (por ejemplo, acceso por IP o por un nombre alternativo).
Solución: use exactamente el host proporcionado por el administrador del entorno en la URL base.
El token es válido, pero se rechaza el envío o la descarga
Síntoma: 403 en /upload, /download/list o /report, con un token aceptado en otras rutas.
Causa probable: una regla del usuario o del entorno impide la operación: servicio deshabilitado, usuario bloqueado, horario no permitido, límite de tamaño, tipo o nombre de archivo, o límite de sesiones simultáneas.
Solución: revise las reglas de acceso con el administrador del servicio.
El inicio de sesión devuelve 206 en lugar de 200
Síntoma: /auth/login responde 206 Partial Content y no crea la cookie de sesión.
Causa probable: el usuario tiene MFA habilitado.
Solución: complete el segundo factor mediante el linkURL recibido, como en Completar el MFA.
El inicio de sesión funciona, pero no encuentro el token en el JSON
Síntoma: la respuesta de /auth/login no tiene ningún campo con el token.
Causa probable: el inicio de sesión local entrega la sesión solo en la cookie __Host-dirl_session.
Solución: guarde y reenvíe la cookie (curl -c y -b) u obtenga un token Bearer mediante el password grant.
El endpoint de token devuelve 400
Síntoma: /auth/token o /oauth2/token responde 400 con error y error_description.
Causa probable: cuerpo enviado en JSON en lugar de formulario, campo obligatorio ausente, grant_type o subject_token_type no válido, JWT de origen no aceptado o proveedor no informado en el token exchange.
Solución: envíe application/x-www-form-urlencoded con los campos de Tokens OAuth y lea error_description.
Las rutas protegidas devuelven 401 después de un tiempo
Síntoma: llamadas que funcionaban pasan a responder 401.
Causa probable: el token o la sesión expiró, o la sesión se finalizó.
Solución: obtenga una nueva credencial y repita la llamada. Consulte Expiración.
El informe devuelve un error
Síntoma: GET /report responde con un error.
Causa probable: no se envió el parámetro obligatorio filterdirection o su valor es diferente de 5 (descargas concluidas) o 7 (cargas concluidas).
Solución: incluya filterdirection. Consulte Consultar informes.
El enlace de descarga, MFA o contraseña no funciona (404 o 400)
Síntoma: un linkURL o un enlace recibido por correo electrónico o SMS devuelve un error.
Causa probable: el enlace expiró, se modificó (por ejemplo, se truncó al copiarlo o se recodificó la query string) o el archivo ya no está disponible.
Solución: use la URL completa, sin modificaciones. Si expiró, genere un nuevo enlace (nuevo listado, nuevo inicio de sesión o nueva solicitud de contraseña).
El archivo descargado está dañado o contiene un mensaje de error
Síntoma: el archivo guardado es demasiado pequeño o contiene texto en lugar del contenido esperado.
Causa probable: la respuesta de error se guardó como si fuera el archivo, o el contenido binario se trató como texto o JSON.
Solución: verifique el estado HTTP antes de guardar (curl --fail) y guarde la respuesta como binario.
El callback de SSO falla durante una prueba
Síntoma: se rechazan las llamadas a /sso/oauth2/cb o /sso/saml2/acs realizadas manualmente.
Causa probable: el proveedor emite y firma state, code y SAMLResponse, que están vinculados a la sesión del navegador.
Solución: pruebe el SSO en el navegador, comenzando en /sso/login?provider=<nombre>. Consulte Single Sign-On.
El inicio de sesión, el primer acceso o la recuperación de contraseña devuelve 400, 403 o 503
Síntoma: /auth/login, /auth/firstaccess o /auth/forget falla antes de validar las credenciales.
Causa probable: el entorno exige Cloudflare Turnstile. 400: header CF-Turnstile-Response ausente o no válido; 403: token rechazado (no válido, caducado o ya utilizado); 503: la API no pudo validar el token con Cloudflare.
Solución: genere un nuevo token del widget en cada intento y envíelo en el header CF-Turnstile-Response. En caso de 503, inténtelo de nuevo. Las integraciones sin navegador deben usar el password grant. Vea Cloudflare Turnstile.