Troubleshooting & Billing
API 错误排查与计费核对
先保留响应信息，再区分鉴权、请求格式、模型分组、余额与临时服务问题。计费争议应以控制台使用记录和可追踪的请求信息核对。
先保存这些信息
- 请求发生的日期、时间和时区；
- 请求端点、HTTP 方法和模型标识；
- HTTP 状态码与完整错误响应体；
- 响应头中的
X-Request-ID（如有）； - 客户端名称与版本、是否流式、发生在首个响应前还是传输中途；
- 本次尝试次数，以及客户端是否启用了自动重试；
- Key 名称或脱敏标识，不要提供完整 API Key。
先排除客户端配置没有生效
- 重新加载配置。修改环境变量或配置文件后，完全退出并重启客户端；终端工具应新开一个终端会话。仅刷新对话窗口不一定会重新读取配置。
- 确认环境变量存在。在启动客户端的同一个用户、终端或服务进程环境中检查变量是否已设置，不要把完整 Key 输出到截图或日志。图形应用通常不会自动继承你在另一个终端临时设置的变量。
- 核对最终请求 URL。确认路径没有变成
/v1/v1/…、/v1/messages/messages，也没有把网页主站地址误当 API 地址。Base URL 的判断方法见OpenAI 兼容接入。 - 检查代理、DNS 和 TLS。确认系统代理、VPN、企业网关或安全软件没有改写请求；从同一设备解析并访问 API 域名，检查系统时间和证书链。不要通过关闭 TLS 校验来绕过错误。
- 用最小请求对照。在同一网络用文档中的
curl最小请求测试。若 curl 成功而客户端失败，优先检查客户端的配置加载、代理和协议；两者都失败时再按响应或网络错误继续定位。
是否重试、是否扣费、何时联系支持
| 现象 | 是否重试 | 是否扣费（怎么确认） | 何时联系支持 |
|---|---|---|---|
400、404：参数、协议、路径或模型错误 | 先不要原样重试。修正 JSON、必填字段、最终 URL、模型标识和 Key 分组后再试一次。 | 按发生时间和 Key 查询使用记录；不能仅凭客户端错误页面推断是否形成费用。 | 已使用站内当前配置和最小请求仍稳定复现，并能提供脱敏响应与请求 ID 时。 |
401、403：鉴权、余额或访问条件 | 先检查鉴权头、Key 状态、额度、有效期、IP 规则、余额和分组，不要用同一错误配置连续重试。 | 在使用记录中逐次核对；如出现无法对应的费用，保留时间、Key 名称和请求 ID。 | 确认 Key 与余额条件正常仍被拒绝，或使用记录和实际尝试无法对应时。 |
429：频率或额度限制 | 降低并发，遵循响应中的等待提示并采用有上限的退避；额度或余额不足应先处理原因。 | 检查每次尝试是否各自形成记录，不要根据状态码作统一假设。 | 低频最小请求持续返回 429，且 Key 额度、余额和限制均无法解释时。 |
5xx：临时服务或上游问题 | 保留请求 ID 后有限次退避重试；会产生外部副作用的请求应先确认结果，避免重复执行。 | 每次尝试都按时间和请求 ID 核对使用记录；错误响应本身不是费用结论。 | 多次退避后持续失败、影响多个模型，或状态页未能解释现象时。 |
| 连接失败、DNS 或 TLS 错误，且尚未建立 API 连接 | 先修正网络、代理、DNS、系统时间或证书链；不要关闭证书校验，也不要高频重试。 | 检查使用记录确认是否有对应调用；本机网络错误文字不能替代站内记录。 | 同一网络的最小请求仍失败，且可提供域名、时间和脱敏网络错误时。 |
| 超时、连接重置或流式响应中断 | 先确认站内记录和客户端是否会自动重试。请求可能已被部分或完整处理，直接重试可能产生重复调用。 | 按开始时间、Key、模型、请求 ID 和尝试次数逐条核对；不要把“未看到完整答案”等同于“没有用量”。 | 持续中断、记录重复或费用无法与尝试次数对应时，携带脱敏证据联系支持。 |
同一状态码可能对应不同原因，响应体中的错误类型和说明优先于上表的通用分类。自动重试会产生新的请求尝试，应设置次数上限和退避，并把实际尝试次数纳入费用核对。
分组和协议不匹配
API Key 与创建时选择的模型分组绑定。应按客户端使用的 OpenAI 兼容协议或 Anthropic Messages 兼容协议选择当前分组。跨协议使用同一把 Key，或请求不属于该分组的模型，都可能失败。
OpenAI 兼容
推荐 Base URL 为 https://api.xmapi.me/v1，Chat Completions 路径为 /v1/chat/completions。
Anthropic Messages
完整 Messages 端点为 https://api.xmapi.me/v1/messages，需使用相应请求格式和分组。
去 /usage 核对用量与费用
- 定位调用。登录控制台并打开
/usage使用记录，按时间、模型或 API Key 名称找到对应调用。 - 对应尝试次数。把客户端重试次数、请求时间和请求 ID 与记录逐条对应；超时或流中断时尤其不要只看最后一次错误。
- 核对计费项。文本模型通常分别记录输入 Token 与输出 Token；图片、缓存或其他能力可能使用不同计费项。
- 核对当时价格。模型单价可能调整，应结合调用发生时的站内记录，而不是用当前价格倒推历史费用。
- 反馈异议。整理时间、模型、用量、费用和请求 ID，从官方支持页进入当前支持渠道，只提供脱敏的问题摘要。
客户端显示失败、超时或未收到完整输出，不足以单独判断服务端处理进度和费用结果；反过来，也不能把所有失败都视为一定产生费用。应以站内可追踪的使用记录逐次核对。字段说明见余额、用量与扣费，具体规则见计费与定价说明。
问题已解决的标志
- 修正配置后，请求返回预期的 HTTP
200和对应协议响应结构。 - 使用记录中能找到该请求，用量、模型和费用字段与实际调用一致。
- 同一请求不再持续出现原错误；临时错误的重试已设置次数上限和退避间隔。
安全地联系支持
以下情况适合从官方支持页进入当前支持渠道：使用站内当前配置和最小请求仍稳定复现；退避后持续出现 5xx 或流中断；使用记录、余额变化与实际尝试次数无法对应；或怀疑 Key 与账户安全受到影响。
反馈时只提供脱敏的问题摘要、发生时间与时区、客户端及版本、端点、模型、HTTP 状态或网络错误、请求 ID、Key 名称和尝试次数。不要发送完整 API Key、密码、验证码、账号、完整订单详情、付款凭证或含私密提示词的完整请求正文。
不要为了排查而反复高频重试失败请求。对于可重试的临时错误，应限制次数并逐步延长等待时间；对参数、权限或余额类错误，先修正原因再重试。