Nội dungLỗi và thử lại
返回文档

错误与重试

通过错误和请求 ID 诊断问题。

HTTP 429 可能来自本地接入压力、队列已满或上游限流。请阅读错误及 Retry-After；这不表示 RPM 或 TPM 无限制。

遵守 Retry-After，使用带随机抖动的指数退避，并限制次数与总时长。视频任务可能已创建时，先查询任务 ID，避免重复提交。

如有 x-apivn-request-id，请连同错误时间保存以便排查。报告中不要包含 API 密钥或敏感请求内容。

错误代码

HTTP错误类型原因
400invalid_request_errorJSON 错误或缺少参数
401authentication_error钥匙丢失、钥匙错误或钥匙被撤销
402insufficient_balance
api_key_monthly_limit
outstanding_undercharge		请读取 error.type：insufficient_balance 表示可用余额不足；api_key_monthly_limit 表示密钥已达到月度消费上限；outstanding_undercharge 表示先前请求尚有待对账的欠款。密钥限额请在 Dashboard → Keys 中检查；充值钱包不会自动提高该限额。
403model_not_allowed此 API 密钥无权使用所选模型。请在 Dashboard → Keys 中检查模型权限，或选择已获授权的模型。
413request_too_large请求体超过 20 MB，或输入超过模型/供应商的独立限制。请阅读错误信息并减少上下文、图片或文件；即使低于网关限制，也可能返回 413。
429rate_limit_errorHTTP 429 可能来自本地接入压力、队列已满或上游限流。请阅读错误及 Retry-After；这不表示 RPM 或 TPM 无限制。
502api_error无法连接上游供应商的模型
503service_unavailable系统正在维护中

余额错误可能包含 required_vnd 和 available_vnd；密钥限额错误可能包含 limit_vnd 和 spent_vnd。请连同 request ID 保存这些字段以便排查，不要分享 API 密钥。

{
  "type": "error",
  "error": {
    "type": "insufficient_balance",
    "message": "余额已过期。前往 https://apivn.dev/dashboard/topup 充值"
  }
}

故障排除

在价格页面查看模型状态

如有 x-apivn-request-id，请连同错误时间保存以便排查。报告中不要包含 API 密钥或敏感请求内容。

遵守 Retry-After，使用带随机抖动的指数退避，并限制次数与总时长。视频任务可能已创建时，先查询任务 ID，避免重复提交。

症状常见原因如何处理
404 或“未找到”原始 URL 粘贴错误 — /v1 多余或缺失。Anthropic工具使用https://apivn.dev；使用 https://apivn.dev/v1 的 OpenAI 风格工具。
401 authentication_error密钥错误、已被撤销或应用程序仍使用旧的保存密钥。在仪表板中创建新密钥，删除应用程序中的旧密钥，然后重新启动应用程序。
402 insufficient_balance钱包余额不足。在充值页面进行充值。
429 rate_limit_errorHTTP 429 可能来自本地接入压力、队列已满或上游限流。请阅读错误及 Retry-After；这不表示 RPM 或 TPM 无限制。遵守 Retry-After，使用带随机抖动的指数退避，并限制次数与总时长。视频任务可能已创建时，先查询任务 ID，避免重复提交。
Claude Code 一直要求登录该设备仍然具有旧 Anthropic 帐户的登录会话。在 Claude Code 中运行 /logout，设置 ANTHROPIC_AUTH_TOKEN，然后重新打开终端。
应用程序显示该模型不存在模型名称输入不正确或应用程序自动添加供应商前缀。调用 GET /v1/models 获取准确名称；若应用不需要，请去掉 anthropic/ 等前缀。
发送照片时出错应用发送了模型不支持的图片格式，或图片过大。Chỉ dùng model có nhãn Vision, nén ảnh và giữ toàn bộ yêu cầu dưới 20 MB.
环境变量没有影响旧终端仍保留旧值，或者应用程序读取单独文件中的配置。打开一个新终端（Windows：注销/重新登录），然后检查应用程序是否具有覆盖环境变量的配置文件。

示例经过源码审查和本地检查，不代表已验证每个应用版本。正式使用前请检查设置、发送小型请求并确认用量。

Support