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

# 错误码速查

> 调用吉吉API 时常见的 HTTP 状态码、原因和处理方法。

请求失败时，先根据状态码定位原因。各工具的专属问题见对应的常见问题页面。

| 状态码 | 含义 | 常见原因 | 处理方法 |
| - | - | - | - |
| `400` | 请求格式错误 | 参数不合法、上下文超出模型上限、图片格式不支持 | 检查请求参数；上下文过长时压缩或新开对话 |
| `401` | 认证失败 | Key 错误、复制不完整、已删除 | 重新复制 Key，检查有没有多余空格 |
| `402` / `403` | 无权限或额度不足 | 余额不足、Key 额度用完、Key 已过期或禁用、分组不包含该模型 | 充值，或在 API 密钥页面检查 Key 的状态和分组 |
| `404` | 地址或模型不存在 | 请求地址多写或少写 `/v1`、模型 ID 拼写错误 | 对照 [请求地址](/quickstart#请求地址) 检查；到模型广场核对模型 ID |
| `413` | 请求体过大 | 上传的图片或文件太大 | 压缩图片或拆分文件 |
| `429` | 请求过于频繁 | 短时间内请求过多，或上游繁忙 | 稍等后重试，降低并发 |
| `500` | 服务内部错误 | 服务端临时异常 | 稍后重试，持续出现请提交工单 |
| `502` / `503` | 上游不可用 | 模型服务临时不可用或正在维护 | 稍后重试，或换一个分组 |
| `504` | 请求超时 | 生成内容过长、思考时间过长 | 调大客户端超时时间，或降低思考强度 |

## 排查步骤

<Steps>
  <Step title="确认请求地址">
    最常见的问题是 `/v1` 写错。Codex 和 OpenAI 兼容客户端需要 `/v1`，Claude Code、Claude Desktop、Gemini CLI 不需要。完整对照见 [快速开始](/quickstart#请求地址)。
  </Step>

  <Step title="确认 Key 和分组">
    在 [API 密钥](https://www.jiji.cc/keys) 页面确认 Key 状态正常、额度充足、所在分组包含要用的模型。
  </Step>

  <Step title="查看使用日志">
    在控制台的使用日志中查看有没有对应的请求记录。没有记录说明请求没有到达吉吉API，重点检查本地配置和网络。见 [用量与日志](/account/usage)。
  </Step>

  <Step title="直接测试接口">
    用 cURL 绕过工具直接测试，判断是工具配置问题还是 Key 问题：

    ```bash theme={null}
    curl https://www.jiji.cc/v1/models \
      -H "Authorization: Bearer your-api-key-here"
    ```

    能返回模型列表，说明 Key 和网络都正常，问题在工具配置。
  </Step>

  <Step title="检查网络">
    连接超时、无法解析域名、SSL 证书错误，见 [网络与代理](/environment/network)。
  </Step>
</Steps>

## 各工具常见问题

<CardGroup cols={2}>
  <Card title="Claude Code" icon="https://mintcdn.com/dark-bf96e504/WbOz9QgQJZLZgWO6/icons/claude.svg?fit=max&auto=format&n=WbOz9QgQJZLZgWO6&q=85&s=1f3e92c0622a6f260673350baca8a82b" href="/claude-code/faq" width="32" height="32" data-path="icons/claude.svg" />

  <Card title="Claude Desktop" icon="https://mintcdn.com/dark-bf96e504/WbOz9QgQJZLZgWO6/icons/claude.svg?fit=max&auto=format&n=WbOz9QgQJZLZgWO6&q=85&s=1f3e92c0622a6f260673350baca8a82b" href="/claude-desktop/faq" width="32" height="32" data-path="icons/claude.svg" />

  <Card title="Codex" icon="https://mintcdn.com/dark-bf96e504/WbOz9QgQJZLZgWO6/icons/openai.svg?fit=max&auto=format&n=WbOz9QgQJZLZgWO6&q=85&s=7dbba00a6c004d949649946c3027d670" href="/codex/faq" width="32" height="32" data-path="icons/openai.svg" />

  <Card title="Gemini CLI" icon="https://mintcdn.com/dark-bf96e504/WbOz9QgQJZLZgWO6/icons/gemini.svg?fit=max&auto=format&n=WbOz9QgQJZLZgWO6&q=85&s=5e4fad5f49829b0b4479e434182ff287" href="/gemini/faq" width="32" height="32" data-path="icons/gemini.svg" />
</CardGroup>


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