# Soluciona problemas de conexión de API, CLI y MCP

URL canónica: https://sosoapi.ai/es/docs/troubleshooting

Resuelve errores de inicio de sesión, permisos, esquema, carga y escrituras inciertas sin exponer credenciales ni duplicar trabajo aceptado.

## Navegador incorrecto o inicio de sesión local bloqueado

Detén el inicio de sesión pendiente y ejecuta auth login --no-open. Abre la URL recién mostrada en el perfil de navegador deseado. Comprueba la cuenta y el espacio de trabajo antes de conceder acceso y usa un solo perfil para ese enlace. Si el puerto 8789 está ocupado, identifica el proceso que escucha y detenlo solo si es un proceso de inicio de sesión que tú iniciaste.

```
npx sosoapi auth login --no-open
```

```
lsof -nP -iTCP:8789 -sTCP:LISTEN
```

## 401, 403 y cuentas no disponibles

Para 401, comprueba que hayas iniciado sesión con una credencial vigente. Para 403, comprueba el rol del espacio, alcance elegido y capacidad requeridos. Usa auth status y verifica el correo de cuenta y tipo de credencial aceptado. Cambia el acceso solo si la operación lo necesita; cambiar el perfil de herramientas no concede permisos.

Comprueba la cuenta social por separado. Consulta su conexión y capacidades, y vuelve a conectar solo si el proveedor necesita renovar el consentimiento. Un error interno del servicio no justifica recrear una conexión sana.

- [Autenticación y permisos](https://sosoapi.ai/es/docs/authentication)

- [Referencia completa de API](https://sosoapi.ai/es/docs/api)

## Validación 400 y desajuste de versiones

Lee el cuerpo de respuesta y las rutas de campos de validación. Los errores de validación pueden contener un ZodError; los del controlador pueden usar error, message y code. Compara la solicitud con el contrato instalado y actualiza el paquete del cliente si hace falta. Corrige los campos indicados sin eliminar valores obligatorios ni añadir filtros no admitidos.

```
npx sosoapi api contract --route /studio-api/scheduled-posts/
```

## 409, 429, 5xx o escritura que agotó el tiempo de espera

Para 409, consulta la versión más reciente del recurso y las acciones disponibles antes de cambiarlo. Para 429, espera según Retry-After y reduce la concurrencia. Si una escritura agota el tiempo de espera o devuelve 5xx, conserva su ID y consulta primero el resultado existente: el servidor puede haberla aceptado antes de fallar la conexión.

Reintenta solo cuando lo permitan la operación y su estado actual. Conserva la misma clave para el mismo payload y no crees un reemplazo para eludir un resultado incierto. Corrige fallos de autenticación antes de reintentar. Si una tarea en segundo plano sigue pendiente, su estado ya puede contener un error de ejecución que convenga comprobar.

- [Referencia de publicación](https://sosoapi.ai/es/docs/publishing-api-reference)

## Problemas de carga o detección de herramientas

La carga local acepta archivos multimedia admitidos de hasta 500 MiB del directorio de trabajo, la carpeta temporal, Pictures/Movies/Videos o carpetas indicadas en SOSOAPI_UPLOAD_ROOTS. Se rechazan carpetas cuyo nombre empieza por punto y enlaces simbólicos que salen de esos directorios. Añade la carpeta multimedia específica que necesitas en vez de todo tu directorio personal. Una conexión HTTP no puede leer archivos locales.

Si faltan herramientas, vuelve a conectar el cliente y compara su perfil y tipo de conexión con la referencia. Comprueba que estén cargadas en la conversación actual; un nombre de servidor guardado no lo confirma por sí solo.

- [Referencia de herramientas MCP](https://sosoapi.ai/es/docs/mcp)

## Comparte diagnósticos útiles de forma segura

Comparte nombre de operación, hora, estado HTTP, código de error seguro y request_id o x-request-id si están disponibles. Incluye la versión de CLI y si usaste MCP local o remoto. Elimina tokens, cookies, enlaces de autorización, URL multimedia firmadas, contenido de clientes e IDs privados. Comparte el error pertinente en vez de un archivo de credenciales o una respuesta completa.

- [Contactar con SosoAPI](https://sosoapi.ai/es/contact)