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

# 错误处理

> 区分参数、鉴权、限流和结果不确定，保留必要排障信息。

## 先检查 HTTP 状态

| 状态 | 常见含义 | 处理方式 |
| - | - | - |
| `400` | 参数不合法、模型未配置或生成失败 | 结合错误内容修正；不要直接循环发送原请求 |
| `401` | API Key 无效、过期或未正确传递 | 检查 Bearer 请求头并联系管理员 |
| `403` | 权限或账户限制，部分额度问题也可能使用该状态 | 核对模型权限、余额、Key 限制及错误消息 |
| `404` | 请求路径不存在 | 检查 API 域名、路径以及是否重复添加 `/v1` |
| `429` | 触发调用限制或暂时容量不足 | 降低并发并遵循服务端提示，不保证所有响应都有 `Retry-After` |
| `500` / `502` / `503` | 服务处理异常或暂不可用 | 保留请求信息，先确认执行状态再决定重试 |
| `504` | 等待生成结果超时 | 结果可能仍会完成，请先核对调用记录 |

具体业务错误与 HTTP 状态的对应并非完全固定。不要仅凭状态码判断是否已产生图片或费用。

## 错误结构

网关错误通常采用以下形式。示例内容是占位信息；`code` 可能为空，`type` 和消息因错误来源而不同：

```json theme={null}
{
  "error": {
    "message": "请求未完成，请结合请求 ID 联系对接人员",
    "type": "new_api_error",
    "code": ""
  }
}
```

客户端应先判断 HTTP 状态，再安全解析响应；中间代理也可能返回非 JSON 内容。不要把解析失败当作生成失败的充分证据。

## 获取排障信息

为 cURL 添加 `-D response.headers` 可保存响应头。该文件保存的是**响应头**，不是含 API Key 的请求头。

```bash theme={null}
# 在已有 cURL 命令中追加以下选项
-D response.headers
```

向对接人员提供：

* 调用时间与时区。
* 请求模型和非敏感参数，如 `size`、`n`。
* HTTP 状态、脱敏后的错误消息。
* 响应头或错误消息中可获得的请求 ID。
* 是生成阶段失败，还是图片下载失败。

不要提交完整 API Key、控制台密码、Cookie、鉴权请求头或含业务机密的完整提示词／参考图。不要使用会把鉴权请求头写入共享日志的 `curl -v` 排障材料。

## 下载失败不需要重新生图

如果生成接口已成功返回图片 URL，只是下载失败，应优先重试下载。重新调用生成接口是新的创建请求，可能产生新的图片与费用。


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