错误结构

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

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

稳定错误码

Code	HTTP status	含义	建议处理
`public_api_disabled`	503	Public API 调用暂时关闭。	稍后重试，或先在 Studio 手动生成。
`api_key_missing`	401	请求没有携带 Bearer API Key。	发送 `Authorization: Bearer rvya_sk_...`。
`api_key_invalid`	401	key 无法校验。	检查 key，必要时轮换。
`api_key_revoked`	401	key 已在 Settings 中禁用。	创建新 key。
`api_key_expired`	401	key 已过期。	创建新 key。
`api_scope_denied`	403	key 缺少所需 scope。	创建包含对应 scope 的 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	当前 Chat session 不能用于该请求。	使用同一账户和同一模型下由 API 创建的 session。
`chat_attachment_not_supported`	400	Chat 附件不支持。	先通过 Files API 上传图片，再传入返回的 `file_id`。
`idempotency_conflict`	409	同一幂等 key 搭配了不同输入。	使用新 key，或重发完全相同的请求体。
`insufficient_credits`	402	账户积分不足。	补充积分，或选择更低成本请求。
`internal_error`	500	请求未能完成。	搭配幂等 key 重试，或带 `requestId` 联系支持。

限流

Rivya 会按 API Key 执行 Public API 应用层限流。生产默认值由 PUBLIC_API_RATE_LIMIT_PER_MINUTE 配置。

收到 rate_limited 后，请使用指数退避，不要密集循环重试。

幂等重试

生产调用 POST /api/v1/generations 和 POST /api/v1/chat/completions 时，建议始终发送 Idempotency-Key。

建议方式：

每个逻辑生成请求生成一个唯一 key
只有重试同一个请求体时才复用同一个 key
把返回的公开任务 ID 保存到你自己的任务记录中
对 Chat API，如果要继续同一段对话，请保存返回的 session_id
不要把同一个 key 用在不同模型、提示词或参数上

如果提交后网络中断，用相同请求体和相同 Idempotency-Key 重试。Rivya 可以返回已保存的公共响应，而不是创建重复任务。

重试判断

这些错误可以退避后重试：

public_api_disabled
rate_limited
internal_error
临时网络失败

这些错误不要在不改输入的情况下反复重试：

api_key_invalid
api_key_revoked
api_scope_denied
validation_failed
webhook_url_rejected
chat_model_not_supported
chat_session_conflict
chat_attachment_not_supported
idempotency_conflict
insufficient_credits

API 错误码与限制

错误结构

稳定错误码

限流

幂等重试

重试判断

相关页面

目录