Solución de problemas

Síntoma: una integración que funcionaba en la versión 8 pasa a recibir 400 en /upload, /download/list o /report.

Causa probable: la llamada envía Authorization: Basic. A partir de la versión 9, estas rutas aceptan solo un token Bearer.

Solución: obtenga un token en POST /oauth2/token (o en el inicio de sesión) y envíe Authorization: Bearer <access_token>. Vea Autenticación en la API.

Síntoma: la API devuelve 401.

Causa probable: usuario inexistente, contraseña incorrecta, o token Bearer caducado o con firma, emisor o audiencia no válidos.

Solución: verifique el usuario y la contraseña registrados en el servidor STCP. Obtenga un nuevo token en /oauth2/token; caduca tras expires_in segundos.

Síntoma: se rechaza el intercambio del JWT del portal de servicios por un token de Riversoft® STCP DirectLink.

Causa probable: la firma del JWT no coincide con la clave registrada para el proveedor, iss o aud no corresponden a la configuración, el token caducó o el usuario de las claims no existe en el servidor STCP.

Solución: verifique que el token se haya firmado con la clave privada correspondiente a la clave registrada y que kid y alg coincidan. Revise el identificador enviado en provider (o en el header X-STCPDIRECTLINK-JWT-ISSUER), el reloj de los servidores y el usuario. Vea JWT de confianza.

Síntoma: POST /oauth2/token devuelve 400.

Causa probable: el cuerpo no tiene el formato application/x-www-form-urlencoded, falta grant_type o, en el token exchange, subject_token_type es distinto de urn:ietf:params:oauth:token-type:jwt.

Solución: envíe el formulario con el header Content-Type: application/x-www-form-urlencoded. En el password grant: grant_type=password&username=<usuario>&password=<contrasena>. La respuesta incluye error y error_description con el motivo.

Síntoma: el token se acepta, pero la llamada devuelve 403.

Causa probable: una regla de acceso bloqueó la operación: conexión del usuario bloqueada, fuera de la ventana horaria, servicio deshabilitado, filtro de archivo, límite de sesiones o host de la URL distinto del configurado para la API.

Solución: use exactamente el host informado por el administrador y pídale que verifique las reglas del usuario en el servidor STCP.

Síntoma: el inicio de sesión, el primer acceso o la recuperación de contraseña devuelve 400, 403 o 503.

Causa probable: 400 indica que no se envió el header CF-Turnstile-Response o que no es válido; 403, que el token fue rechazado (no válido, caducado o ya utilizado); 503, que el servidor no pudo validar el token con Cloudflare.

Solución: genere un nuevo token del widget en cada intento (es de un solo uso y caduca en 300 segundos). En caso de 503, inténtelo de nuevo; si persiste, el administrador debe verificar la salida HTTPS del servidor a challenges.cloudflare.com.

Síntoma: GET /auth/firstaccess devuelve 403.

Causa probable: el usuario ya realizó el primer acceso.

Solución: use Olvidó la contraseña para restablecer la contraseña.

Síntoma: un archivo ya descargado no aparece en /download/list.

Causa probable: después de la descarga, el archivo pasa al área de backup.

Solución: consulte /download/list/backup y descárguelo de nuevo mediante el linkURL devuelto, mientras la política de retención lo permita.

Síntoma: la lista devuelve como máximo 100 archivos.

Causa probable: la lista está paginada.

Solución: incremente el parámetro page a partir de 0 hasta recibir una lista vacía.

Síntoma: la dirección /portal devuelve 404 o el portal no carga su configuración.

Causa probable: el config.json del portal no se creó a partir de example-config.json, o la ruta de las páginas estáticas del servicio de la API en la instancia no es la predeterminada.

Solución: cree el config.json a partir de la plantilla (vea Configuración de Riversoft STCP DirectLink Portal) y verifique, en el servicio de red de la API de la instancia, que la ruta de las páginas estáticas sea /usr/local/stcpdirectlink/static, sin barra al final.