錯誤結構

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

請在要求 Rivya support 調查失敗 API 請求時，於日誌中保留 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	body、模型、提示詞或 params 無效。	對照模型參考檢查 body。
`not_found`	404	要求的任務不存在，或不屬於該帳號。	檢查公開 task ID 和帳號邊界。
`webhook_url_rejected`	400	webhook endpoint URL 不被允許。	使用不含 credentials、fragments、localhost 或私人網路位址的 HTTPS 公開 URL。
`chat_model_not_supported`	400	所選模型不適用於 Chat API。	讀取 `/api/v1/models` 並選擇可用的 chat 模型。
`chat_session_conflict`	409	這個聊天工作階段不能用於此請求。	使用同一帳號和模型所擁有的 API 建立工作階段。
`chat_attachment_not_supported`	400	不支援這個聊天附件。	透過 Files API 上傳圖片，並傳入它的 `file_id`。
`idempotency_conflict`	409	相同冪等 key 以不同輸入重複使用。	使用新 key，或重新送出完全相同的 body。
`insufficient_credits`	402	帳號沒有足夠點數。	增加點數，或選擇成本較低的請求。
`internal_error`	500	請求無法完成。	使用冪等性重試，或帶著 `requestId` 聯絡 support。

速率限制

Rivya 會依每個 API key 套用應用層 Public API 速率限制。預設 production 限制由 PUBLIC_API_RATE_LIMIT_PER_MINUTE 設定。

收到 rate_limited 時，請使用指數退避。不要以緊密迴圈重試。

冪等重試

每個 production 請求都應傳送 Idempotency-Key：POST /api/v1/generations 和 POST /api/v1/chat/completions。

建議模式：

每個邏輯生成請求產生一個唯一 key
只有在重試相同 body 時，才重複使用相同 key
將回傳的公開 task ID 與你自己的 job record 一起儲存
對於 Chat API，如果你想繼續同一段對話，請儲存回傳的 session_id
不要將同一個 key 用於不同模型、提示詞或 params

如果送出後網路失敗，請用相同 body 和相同 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 錯誤與限制

錯誤結構

穩定錯誤碼

速率限制

冪等重試

重試判斷

相關頁面

目錄