↓
Rivya AI 文档

API 错误码与限制

处理 Rivya API 公共错误码、HTTP 状态、限流、幂等冲突和重试策略。

最近审阅于 2026年11月5日

Rivya API 使用稳定的公共错误码返回 JSON。集成时应把 error.code 当作错误合同。

错误结构

请求错误不一定是生成失败,已有 ID 时先检查原任务状态。聊天串流开始后的错误会通过 SSE error 事件发送,HTTP 可能已为 200,需同时读取事件,见聊天 API。向支持提供 requestId,不要提供 API 密钥。

{
  "error": {
    "code": "api_key_missing",
    "message": "A valid Bearer API key is required.",
    "requestId": "req_..."
  }
}

如果需要排查失败请求,请在自己的日志中保留 requestId。

稳定错误码

CodeHTTP status含义建议处理
public_api_disabled503公开 API 当前关闭。等待 API 恢复;工作台可用性另行判断。
api_key_missing401请求没有携带 Bearer API Key。发送 Authorization: Bearer rvya_sk_...。
api_key_invalid401key 无法校验。检查 key,必要时轮换。
api_key_revoked401Key 已停用,或所属账户无法使用它。检查密钥;账户受限时联系支持,换 Key 不会解除限制。
api_key_expired401key 已过期。创建新 key。
api_scope_denied403Key 缺少所需权限。使用具备该端点所需权限的 Key。
rate_limited429达到请求频率限制,或上传并发容量暂时已满。降低频率并退避重试。
validation_failed400请求体、模型、提示词或参数无效。对照模型参考修正请求体。
not_found404模型或资源不存在,或当前账户无权访问。核对资源 ID;任务、文件及会话须使用所属账户。
webhook_url_rejected400webhook endpoint URL 不被允许。使用公开 HTTPS URL,不带 credentials、fragment、localhost 或私有网络地址。
chat_model_not_supported400所选模型当前不支持 Chat API。读取 /api/v1/models,选择可用的 Chat 模型。
chat_session_conflict409会话不能用于当前聊天请求。检查 API 会话、所属账户、模型、工具预设与请求是否匹配。
chat_attachment_not_supported400附件不可用或不受此请求支持。先确认模型支持图片,使用所属账户可用的图片 file_id,并核对格式及数量上限。
idempotency_conflict409同键输入已改变,或原请求尚无已存响应。先查原操作;输入不变但仍待定时等待,再用同键重试,不要直接换键。
insufficient_credits402账户余额不足以支持请求。先查余额和所需预留,再决定补充积分或调整请求。
internal_error500Rivya 未能完成请求。先查已有任务或会话;按原幂等键谨慎重试,或带 requestId 联系支持。

限流

生成提交、文件上传、普通聊天和串流聊天按 API Key 分别计数,使用一分钟窗口,当前限额由部署配置。上传另共享并发名额,即使 Key 未达频率限额,并发已满仍可返回 rate_limited。

生成使用 PUBLIC_API_RATE_LIMIT_PER_MINUTE,文件使用 PUBLIC_API_FILE_RATE_LIMIT_PER_MINUTE;两种聊天均使用 PUBLIC_API_CHAT_RATE_LIMIT_PER_MINUTE,但计数器各自独立。这些不是请求参数。收到限流后增加间隔、加随机抖动并限制重试次数;当前响应不保证有 Retry-After。

幂等重试

在 POST /api/v1/generations、POST /api/v1/chat/completions 和 POST /api/v1/chat/completions/stream 首次提交时发送 Idempotency-Key,不超过 128 个字符。每个生成或聊天轮次用唯一键;重试同一操作时保持同一键、请求体与 API Key,并保存任务 ID 或 session_id。主动修改模型、提示词、消息、附件或参数才视作新操作并换键。

断连后结果可能不明,同键同体重试可返回已存响应,不应仅因丢失响应就换新键。已存结果可能成功也可能是错误,重放错误不会重做请求;原响应尚未保存时,即使请求不变也可能返回 idempotency_conflict,应等待并检查原操作。

串流不会重放历史 token 增量,已完成轮次会返回包含已保存结果的简短 SSE 序列。事件与会话读取见聊天 API。

重试判断

rate_limited 应退避重试;public_api_disabled 应等待 API 恢复。网络中断或 internal_error 时先检查已有任务或会话,再按幂等规则谨慎重试;这些响应都不保证下一次成功。

鉴权、权限、输入、Webhook URL、模型、会话、附件或余额问题,应先修正对应原因,不要原样反复提交无效请求。idempotency_conflict 要区分已变更的请求体与原响应待定:只为主动创建的新操作换键,不要在原结果不明时制造重复付费请求。

常见问题

状态查询失败是否表示生成失败?

不是。查询错误只表示没有取得新状态。保留已知状态,按需重试查询;只有任务返回 status: failed 才按失败处理。

聊天流意外关闭后能否重试?

先检查已知的 API 会话是否保存了完整助手回复,断流可能让结果不明。重试同一轮次须保持原请求体与幂等键;已保存的完成结果会重放为简短结果序列,不会重放历史增量。

同一幂等键是否总会重新执行请求?

不会。它可能返回已保存的成功、错误,或在原响应待定时返回冲突。先确认原操作,再决定是否创建新请求。

相关页面