> ## Documentation Index
> Fetch the complete documentation index at: https://wiki.llm.sg/llms.txt
> Use this file to discover all available pages before exploring further.

# 错误排查与常见问题

> 排查鉴权、模型、接口路径、限流和超时问题，整理脱敏后的反馈信息。

请求失败时，先记录实际 HTTP 状态码和错误消息，再检查 API 地址、密钥、模型 ID、账户状态和请求参数。

## 常见 HTTP 状态

下表是通用排查方向，不构成 llm.sg 完整错误码定义。平台或上游可能使用不同状态码，优先阅读实际错误消息。

| 状态码 | 排查方向 |
| - | - |
| `400` | 检查 JSON 格式、必填字段、模型参数和输入长度 |
| `401` | 检查是否携带有效 `Authorization: Bearer ...`，密钥是否已失效 |
| `402` | 若返回该状态，检查额度及实际错误中的付款要求 |
| `403` | 检查账号、密钥及模型访问权限 |
| `404` | 检查路径和模型 ID，特别是 `/v1` 是否遗漏或重复 |
| `429` | 根据错误消息区分速率、并发或额度限制；有 `Retry-After` 时按其提示处理 |
| `500`、`502`、`503`、`504` | 可能涉及网关、服务端或上游错误，记录请求 ID 并稍后重试 |

## “未提供令牌”怎么办？

确认请求中包含以下请求头：

```http theme={null}
Authorization: Bearer YOUR_LLM_SG_API_KEY
```

环境变量需要在运行程序的同一个环境中可见。不要把占位符当成密钥，也不要将浏览器登录状态当成 API 凭证。

2026-11-05 对 `GET https://api.llm.sg/v1/models` 的无密钥检查确实返回了 `401` 和“未提供令牌”。该检查只验证了此端点的鉴权要求。

## Base URL 应该填写什么？

API 域名为 `https://api.llm.sg`。本稿的兼容 SDK 示例填写 `https://api.llm.sg/v1`；直接调用对话接口的完整地址为 `https://api.llm.sg/v1/chat/completions`，后者仍需完成接口验证。

第三方应用可能自动追加 `/v1`。根据它的配置说明和实际请求 URL 排查重复路径。

## 模型不存在或不可用怎么办？

重新获取当前密钥可访问的模型列表，复制完整模型 ID。随后检查模型权限、账户状态及模型当前可用情况。模型在其他平台上的名称不一定能直接用于 llm.sg。

## 从其他服务迁移要改什么？

对于兼容的文本对话接入，先调整 Base URL、API Key 和模型 ID，并用最小请求验证。再逐项验证已有的流式输出、工具、图片及结构化输出功能。其他平台的供应商路由参数或专属请求头需要单独确认，不能直接视为 llm.sg 支持。

## 为什么没有持续输出？

检查是否启用 `stream`，客户端是否逐块读取，以及反向代理是否缓冲响应。先在本地运行最小示例，再检查部署环境。不同模型的首段内容等待时间可能不同。

## 超时或限流后如何重试？

对临时网络错误、限流或部分服务端错误，可以采用有上限的指数退避并增加随机等待。认证、权限或参数错误通常需要先修正原因。

检查 SDK 是否已自动重试，避免与应用层重试叠加。超时可能发生在服务端已开始生成之后，重新请求可能产生额外消耗，也无法保证获得相同输出。

## 反馈问题需要提供什么？

* 请求发生时间和时区。
* 接口路径与请求方法。
* 模型 ID、HTTP 状态码和脱敏后的错误消息。
* 响应中的请求 ID，例如实际返回的 `x-request-id` 或错误消息中的 request id。
* 客户端或 SDK 版本，以及删除密钥和敏感输入后的最小复现示例。

通过平台实际提供的支持入口提交。不要发送完整 API Key、支付凭据或包含敏感用户内容的原始日志。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.