开发者文档
排查 API、CLI 和 MCP 连接问题
解决登录、权限、schema、上传及写入结果不明的失败，同时避免暴露凭证或重复执行已接受的工作。
阅读 Markdown由 SosoAPI 团队审核 ·
错误浏览器或本地登录受阻
停止待处理的登录，再执行 auth login --no-open。在你要使用的浏览器用户配置中开启新输出的 URL。授权前检查账号与工作区，且同一登录链接仅使用一个浏览器用户配置。如果连接埠 8789 已被占用，请确认监听程序，仅在它是你启动的登录程序时停止。
npx sosoapi auth login --no-openlsof -nP -iTCP:8789 -sTCP:LISTEN401、403 与不可用账号
遇到 401，请确认已使用有效凭证登录。遇到 403，请检查工作区角色、所选范围及操作所需能力。使用 auth status 验证账号电子邮箱与接受的凭证类型。只有操作需要时才变更访问权限；切换工具配置不会授予权限。
另行检查社交账号。读取连接与能力，只有平台需要重新同意时才重新链接。内部服务错误不是重建健康连接的理由。
400 验证与版本不一致
读取响应内容与验证字段路径。验证错误可能包含 ZodError；处理程序错误可能使用 error、message 及 code 字段。将请求与已安装契约比对，并视需要更新客户端套件。修正错误指出的字段，不要移除必填值或加入不支持的筛选条件。
npx sosoapi api contract --route /studio-api/scheduled-posts/409、429、5xx 或写入超时
遇到 409，请先读取资源最新版本与可用操作，再进行变更。遇到 429，请依 Retry-After 等待并降低并行数。如果写入逾时或返回 5xx，请保留其 ID 并先检查现有结果：服务器可能已在连接失败前接受请求。
只有该操作及当前状态允许时才重试。相同载荷请保留相同键，不要创建替代项目来绕过不确定结果。重试前先修正验证失败。若背景工作仍待处理，其状态可能已包含值得检查的执行错误。
上传或工具探索问题
本地上传接受工作目录、暂存文件夹、Pictures/Movies/Videos 或 SOSOAPI_UPLOAD_ROOTS 所列文件夹内，上限 500 MiB 的支持媒体文件。拒绝点开头文件夹，以及超出这些根目录的符号链接。请加入实际所需媒体文件夹，而非整个家目录。HTTP 连接无法读取本地文件。
如果缺少工具，请重新链接客户端，并对照参考检查配置与连接类型。确认工具已加载当前对话；仅有已存储的服务器名称不足以证明这点。
安全分享有用的诊断信息
分享操作名称、时间、HTTP 状态、安全错误码，以及可获取的 request_id 或 x-request-id。请附上 CLI 版本及使用本地或远端 MCP 的信息。移除令牌、cookies、授权链接、签署媒体 URL、客户内容及私人 ID。请分享相关错误，而非凭证文件或完整响应。