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

# API 调用常见问题

> NexusAPI：API 调用常见问题

本页适用于 Claude Code、Codex CLI、Cursor、VS Code 插件和自建程序。遇到错误时，先保存**错误原文、Request ID、发生时间、模型和请求接口**；不要发送完整 API Key。

<Tip>
  **先判断再重试**

  参数、接口或会话兼容问题不会因重复请求自动恢复。只对明确的短暂波动做一次低频重试，避免重复任务和额外消费。
</Tip>

## `status_code=500, not implemented`

如果错误原文同时包含 `status_code=500` 和 `not implemented`，且请求使用 `/v1/responses` 调用的是当前平台的 **Anthropic 类型 Claude 渠道**，这是**接口协议不兼容**，不是等待即可恢复的上游故障。new-api rc4 虽然提供了 `/v1/responses` 路由，但 Anthropic 渠道没有 Responses 请求转换实现。

处理方式：

1. 自建程序请改用 OpenAI Chat Completions：`/v1/chat/completions`。
2. Claude Code 请按[Claude Code 教程](/tools/claude-code)配置，不要把 Responses 请求直接发送给 Claude 模型。
3. 不要原样重试；该错误不会因为等待或切换网络自动恢复。

如需协助，请提供不含 API Key 的请求示例、模型名和 Request ID。

## 400 Bad Request / 参数不兼容

通常是请求格式、参数或会话状态不符合当前接口要求。

依次检查：

1. 模型 ID 是否从模型广场准确复制。
2. 接口是否与模型和客户端匹配；请先看[接入方式总览](/guide/integration-overview)。
3. 是否使用了当前模型不支持的图片、工具调用、推理或会话续接参数。
4. 客户端或 SDK 是否为较新版本。
5. 新建会话、发送简短文本后是否仍出现。

不要无修改地反复提交同一请求。

## 401 Unauthorized

常见原因：API Key 缺失、填写错误、已禁用/过期，或鉴权头格式不正确。

```http theme={"system"}
Authorization: Bearer YOUR_API_KEY
```

请从控制台重新复制 Key，并确认请求地址正确。不要将完整 Key 发给客服；如果 Key 已泄露，应立即禁用并重新创建。

## 403 Forbidden

403 表示本次请求被拒绝。平台侧常见原因包括：当前 Key 无权使用所选分组、Key 启用了模型限制、IP 白名单不匹配，或账号状态不可用；也可能是上游模型服务返回的拒绝。

先核对 Key 的分组、模型限制和 IP 白名单，再用一条简短文本验证。若持续出现，请提供 Request ID、模型、时间和错误原文；不要通过反复更换 Key 或高频重试来规避限制。

## 404 Not Found / 请求地址错误

优先检查：

* Base URL 是否重复拼接为 `/v1/v1/...`。
* 客户端是否自动补全了 `/v1` 或具体接口路径。
* 请求路径是否是平台支持的接口，例如 `/v1/chat/completions`、`/v1/responses`、`/v1/messages`、`/v1/images/generations`。

不同工具的地址填写规则不同，请使用对应的[工具教程](/tools/)。

模型 ID 不可用通常不是 404：在 new-api rc4 中，模型不在当前 Key 分组、渠道被禁用或没有可路由渠道时，更常见的是 `503` / `no available channel`。

## 429 Too Many Requests

429 可能来自平台的模型请求频率限制，也可能是模型服务的短时限流。`Concurrency limit exceeded for user` 这类原文通常来自上游或客户端自身的并发限制，不应仅凭状态码认定为平台 Key 故障。

* 降低并发，按响应中的 `Retry-After` 优先等待；没有该字段时再使用带随机抖动的指数退避。
* 不要让多个程序以同一 Key 同时高频重试。
* 低频调用仍持续出现时，请提供 Request ID；我们会核查服务侧可用性。

## 500、502、503、504 或 524

除本页开头的 `not implemented` 外，这些状态通常表示处理失败、连接中断、服务繁忙或等待超时，不一定是您的 Key 或提示词有问题。

| 状态码                   | 建议                                  |
| --------------------- | ----------------------------------- |
| `500` / `502` / `503` | 等待 10～30 秒后只重试一次；持续发生时提交 Request ID |
| `504` / `524`         | 尝试缩短上下文、工具调用或输出长度；稍后再试              |

同一模型连续失败时，请不要持续重复提交长任务。保留现场后联系我们即可。

## `no available channel` / 当前模型暂无可用服务

这表示 new-api rc4 在当前 Key 使用的分组下，没有找到“已启用且承载该模型”的可路由渠道。模型 ID 拼写错误、模型未在分组上架、渠道被禁用或渠道暂时不可用，都可能触发此错误。请稍后重试，或改用模型广场中当前分组可见的其他模型。

若持续出现，请提交模型名、Request ID 和时间；无需重新充值或重复创建 Key。

## `Concurrency limit exceeded for user`

当前账号的并发请求数已达到上限。请等待正在进行中的请求结束，降低客户端并发后再试。不要因为这个错误禁用或重新创建 API Key。

## 长会话或工具调用错误

### `Invalid signature in thinking block`

当前会话中保存的思考内容无法继续校验，常见于长会话恢复、客户端状态变化或兼容性变化。

请新建会话、更新客户端，并避免在多个设备继续同一会话；原会话通常无法通过反复重试恢复。

### `previous_response_id is only supported on Responses WebSocket v2`

客户端在不支持的连接方式上续接了此前响应。请新建会话，关闭实验性的会话续接/响应复用功能，或更新客户端。

### `Content block not found`

客户端没有收到预期的完整内容片段，常见于长会话、工具调用或流式响应中断。请先新建会话、缩短输入并发送简单测试。详见 [Content block not found](/faq/content-block-not-found)。

## 图片生成超时或能力不支持

图片模型只能调用图片接口，文本模型不能调用图片生成接口。当前图片生成使用同步请求，可能需要较长等待时间；不要在未确认结果前连续重复提交同一图片任务。

* `Image generation is not enabled` / `model not supported`：检查模型、接口和参数是否匹配。
* `504` / `524` / 客户端超时：保留 Request ID 和发生时间，不要立即重复生成。

请阅读[图片模型使用说明](/guide/image-generation)。

## 余额正常却提示额度不足

先核对账号余额、该 API Key 的额度上限、有效期和所属分组。不要仅因一次提示就重复充值；持续出现时，请提供 Request ID 供我们核查。

## 错误后是否会自动成功？

不要把一次错误理解为平台随后一定会自动完成。当前不对普通调用承诺平台级自动重试；如果客户端或程序自行再次发起请求，通常会产生新的 Request ID。

判断结果时，以客户端是否收到完整内容和对应 Request ID 的最终记录为准。怀疑重复扣费时，请提供相关 Request ID 和发生时间。

## 联系支持时请一次性提供

```text theme={"system"}
发生时间（含时区）：
Request ID：
模型：
请求接口：
客户端或 SDK 版本：
是否流式 / 图片 / 工具调用：
完整错误原文或截图：
偶发还是持续发生：
```

请勿提交完整 API Key、密码、隐私数据或完整业务内容。API Key 最多提供末 6 位。