エラー形式

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

失敗した API リクエストについて Rivya サポートに調査を依頼する場合は、ログに requestId を残してください。

安定したエラーコード

コード	HTTP status	意味	推奨アクション
`public_api_disabled`	503	Public API 呼び出しが一時的に無効化されています。	後でリトライするか、Studio を手動で使ってください。
`api_key_missing`	401	リクエストに Bearer API キーが含まれていません。	`Authorization: Bearer rvya_sk_...` を送信してください。
`api_key_invalid`	401	キーを検証できません。	キーを確認し、必要ならローテーションしてください。
`api_key_revoked`	401	キーが Settings で失効されています。	新しいキーを作成してください。
`api_key_expired`	401	キーが有効ではなくなっています。	新しいキーを作成してください。
`api_scope_denied`	403	キーに必要なスコープがありません。	必要なスコープを含むキーを作成してください。
`rate_limited`	429	現在のウィンドウ内のリクエストが多すぎます。	バックオフして後でリトライしてください。
`validation_failed`	400	body、モデル、プロンプト、または params が無効です。	body をモデルリファレンスと比較してください。
`not_found`	404	要求されたタスクが存在しないか、アカウントに所有されていません。	公開タスク ID とアカウント境界を確認してください。
`webhook_url_rejected`	400	webhook endpoint URL が許可されていません。	credentials、fragments、localhost、プライベートネットワークアドレスを含まない公開 HTTPS URL を使ってください。
`chat_model_not_supported`	400	選択したモデルは Chat API で利用できません。	`/api/v1/models` を読み取り、利用可能なチャットモデルを選んでください。
`chat_session_conflict`	409	そのチャットセッションはこのリクエストで使用できません。	同じアカウントとモデルに所有される API 作成セッションを使ってください。
`chat_attachment_not_supported`	400	チャット添付がサポートされていません。	Files API で画像をアップロードし、その `file_id` を渡してください。
`idempotency_conflict`	409	同じ冪等性キーが異なる入力で再利用されました。	新しいキーを使うか、まったく同じ body を再送してください。
`insufficient_credits`	402	アカウントに十分なクレジットがありません。	クレジットを追加するか、低コストのリクエストを選んでください。
`internal_error`	500	リクエストを完了できませんでした。	冪等性を使ってリトライするか、`requestId` を添えてサポートに連絡してください。

レート制限

Rivya は API キーごとに、アプリケーションレベルの Public API レート制限を適用します。本番のデフォルト制限は PUBLIC_API_RATE_LIMIT_PER_MINUTE で設定されます。

rate_limited を受け取ったら、指数バックオフを使ってください。短いループで連続リトライしないでください。

冪等なリトライ

本番環境のすべての POST /api/v1/generations と POST /api/v1/chat/completions リクエストには、Idempotency-Key を送信してください。

推奨パターンは次のとおりです。

論理的な生成リクエストごとに一意のキーを生成する
同じ body をリトライする場合にのみ同じキーを再利用する
返された公開タスク ID を自分のジョブ記録に保存する
Chat API では、同じ会話を続行したい場合に返された session_id を保存する
1 つのキーを別のモデル、プロンプト、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 エラーと制限

エラー形式

安定したエラーコード

レート制限

冪等なリトライ

リトライ判断

関連ページ

目次