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

# 错误码与排查

> 按状态码、错误类型与请求 ID 排查调用失败。

排查失败时，先保存 HTTP 状态码和脱敏后的响应正文；响应中有 `X-Maxx-Request-ID` 时一并保留。错误可能包含 `error.message`、`error.type`、`error.code` 和 `retryable`，但不同接口的错误结构不完全相同，不要依赖每次都返回全部字段。

![APIONE 请求日志错误排查入口](https://mintcdn.com/apione/pAFvFGkbmcRZirTZ/images/ui/request-logs.png?fit=max\&auto=format\&n=pAFvFGkbmcRZirTZ\&q=85\&s=093db383e228008dc3c42cb6a7849d28)

先在请求明细中定位失败记录，再结合状态、耗时、模型和请求 ID 排查。

## 按状态码处理

| 状态码 | 常见含义 | 首要处理 |
| - | - | - |
| 400 | 请求、模型或参数不合法 | 核对模型，移除可选参数后重试最小请求 |
| 401 | 密钥缺失、无效、禁用或过期，或鉴权信息冲突 | 检查密钥状态，只保留所需的一种鉴权方式 |
| 402 | 余额不足 | 在控制台核对余额与预估用量 |
| 403 | 无模型权限 | 检查 Key 的可用模型和权限 |
| 404 | 路径不存在，或模型参数查询未找到目标模型 | 检查完整 URL；查询参数时核对模型 ID 与访问权限 |
| 413 | 请求过大 | 减少输入或历史消息 |
| 422 | 预估费用超过单次请求上限 | 阅读错误正文，检查输入长度和输出上限 |
| 429 | Key 并发或上游限流 | 降低并发；有 `Retry-After` 时遵守其等待时间 |
| 500 / 502 / 503 | 网关或上游暂时异常 | 有限重试；持续失败时联系支持 |

表格依据 [APIONE 错误说明](https://apione.ai/zh/api-docs/docs/errors)，具体判断以响应正文为准。模型参数接口也可能返回 `{"error":"model not found"}`，不能只读取 `error.code`。

## 定位顺序

1. 确认 HTTPS 请求发往 `api.apione.ai`，按[接口地址](https://apione.ai/docs/api/overview.md)检查路径拼接。
2. 用相同协议发送最小文本请求，核对[模型 ID](https://apione.ai/docs/models/catalog.md)、密钥权限和余额。
3. 最小请求成功后，逐项恢复可选参数，定位不兼容字段。
4. 如果 cURL 成功而项目失败，检查环境变量、SDK 实际地址、重复的 `/v1` 和代理设置，见[SDK 接入](https://apione.ai/docs/guides/sdks.md)。

## 常见错误标识

| 标识 | 优先检查 |
| - | - |
| `model_not_supported` | 模型是否可用、ID 是否准确 |
| `API_KEY_MODEL_DENIED` | 当前 Key 是否有目标模型权限 |
| `unsupported_parameter` | 该模型是否支持请求中的参数 |
| `context_length_exceeded` | 输入、历史消息与输出上限是否超过模型限制 |

## 重试原则

先修正配置、权限和余额错误。只对可恢复错误做有次数上限的重试，并核对 SDK 是否已自动重试，避免叠加请求。

流开始后仍可能失败，HTTP 200 不足以证明生成已完成。保留已收到的内容和错误，避免静默重发导致重复生成；见[流式处理](https://apione.ai/docs/models/streaming.md)。

## 联系支持前

提供请求时间与时区、协议与端点、模型 ID、HTTP 状态、请求 ID、SDK 或客户端版本、脱敏错误正文及已重试次数。不要发送完整密钥或敏感业务内容。可直接使用[反馈模板](https://apione.ai/docs/support/contact.md)。


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