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。
稳定错误码
| Code | HTTP status | 含义 | 建议处理 |
|---|---|---|---|
public_api_disabled | 503 | 公开 API 当前关闭。 | 等待 API 恢复;工作台可用性另行判断。 |
api_key_missing | 401 | 请求没有携带 Bearer API Key。 | 发送 Authorization: Bearer rvya_sk_...。 |
api_key_invalid | 401 | key 无法校验。 | 检查 key,必要时轮换。 |
api_key_revoked | 401 | Key 已停用,或所属账户无法使用它。 | 检查密钥;账户受限时联系支持,换 Key 不会解除限制。 |
api_key_expired | 401 | key 已过期。 | 创建新 key。 |
api_scope_denied | 403 | Key 缺少所需权限。 | 使用具备该端点所需权限的 Key。 |
rate_limited | 429 | 达到请求频率限制,或上传并发容量暂时已满。 | 降低频率并退避重试。 |
validation_failed | 400 | 请求体、模型、提示词或参数无效。 | 对照模型参考修正请求体。 |
not_found | 404 | 模型或资源不存在,或当前账户无权访问。 | 核对资源 ID;任务、文件及会话须使用所属账户。 |
webhook_url_rejected | 400 | webhook endpoint URL 不被允许。 | 使用公开 HTTPS URL,不带 credentials、fragment、localhost 或私有网络地址。 |
chat_model_not_supported | 400 | 所选模型当前不支持 Chat API。 | 读取 /api/v1/models,选择可用的 Chat 模型。 |
chat_session_conflict | 409 | 会话不能用于当前聊天请求。 | 检查 API 会话、所属账户、模型、工具预设与请求是否匹配。 |
chat_attachment_not_supported | 400 | 附件不可用或不受此请求支持。 | 先确认模型支持图片,使用所属账户可用的图片 file_id,并核对格式及数量上限。 |
idempotency_conflict | 409 | 同键输入已改变,或原请求尚无已存响应。 | 先查原操作;输入不变但仍待定时等待,再用同键重试,不要直接换键。 |
insufficient_credits | 402 | 账户余额不足以支持请求。 | 先查余额和所需预留,再决定补充积分或调整请求。 |
internal_error | 500 | Rivya 未能完成请求。 | 先查已有任务或会话;按原幂等键谨慎重试,或带 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 会话是否保存了完整助手回复,断流可能让结果不明。重试同一轮次须保持原请求体与幂等键;已保存的完成结果会重放为简短结果序列,不会重放历史增量。
同一幂等键是否总会重新执行请求?
不会。它可能返回已保存的成功、错误,或在原响应待定时返回冲突。先确认原操作,再决定是否创建新请求。
