Behandle öffentliche Rivya API-Fehlercodes, HTTP-Statuswerte, Rate Limits, Idempotenzkonflikte und Retry-Entscheidungen.

Die Rivya API gibt stabile öffentliche Fehlercodes als JSON zurück. Behandle den Wert error.code als Integrationsvertrag.

Fehlerformat

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

Bewahre requestId in deinen Logs auf, wenn du den Rivya Support bittest, eine fehlgeschlagene API-Anfrage zu untersuchen.

Stabile Fehlercodes

Code	HTTP status	Bedeutung	Empfohlene Aktion
`public_api_disabled`	503	Public-API-Aufrufe sind vorübergehend deaktiviert.	Später erneut versuchen oder Studio manuell verwenden.
`api_key_missing`	401	Die Anfrage enthielt keinen Bearer API Key.	`Authorization: Bearer rvya_sk_...` senden.
`api_key_invalid`	401	Der Key kann nicht verifiziert werden.	Key prüfen und bei Bedarf rotieren.
`api_key_revoked`	401	Der Key wurde in den Einstellungen widerrufen.	Neuen Key erstellen.
`api_key_expired`	401	Der Key ist nicht mehr gültig.	Neuen Key erstellen.
`api_scope_denied`	403	Der Key hat nicht den erforderlichen Scope.	Key mit dem benötigten Scope erstellen.
`rate_limited`	429	Zu viele Anfragen im aktuellen Zeitfenster.	Zurückgehen und später erneut versuchen.
`validation_failed`	400	Body, Modell, Prompt oder Params sind ungültig.	Body mit der Modellreferenz vergleichen.
`not_found`	404	Der angefragte Task existiert nicht oder gehört nicht zum Konto.	Öffentliche Task-ID und Kontogrenze prüfen.
`webhook_url_rejected`	400	Die Webhook-Endpoint-URL ist nicht erlaubt.	Öffentliche HTTPS-URL ohne Credentials, Fragmente, localhost oder private Netzwerkadressen verwenden.
`chat_model_not_supported`	400	Das gewählte Modell ist für Chat API nicht verfügbar.	`/api/v1/models` lesen und ein verfügbares Chat-Modell wählen.
`chat_session_conflict`	409	Die Chat-Session kann für diese Anfrage nicht verwendet werden.	Eine API-erstellte Session verwenden, die demselben Konto und Modell gehört.
`chat_attachment_not_supported`	400	Der Chat-Anhang wird nicht unterstützt.	Ein Bild über Files API hochladen und dessen `file_id` übergeben.
`idempotency_conflict`	409	Derselbe Idempotency Key wurde mit anderem Input wiederverwendet.	Neuen Key verwenden oder exakt denselben Body erneut senden.
`insufficient_credits`	402	Das Konto hat nicht genug Credits.	Credits hinzufügen oder eine günstigere Anfrage wählen.
`internal_error`	500	Die Anfrage konnte nicht abgeschlossen werden.	Mit Idempotenz erneut versuchen oder Support mit `requestId` kontaktieren.

Rate Limits

Rivya wendet Public-API-Rate-Limits auf Anwendungsebene pro API Key an. Das Standardlimit für Produktion wird über PUBLIC_API_RATE_LIMIT_PER_MINUTE konfiguriert.

Wenn du rate_limited erhältst, nutze exponentielles Backoff. Versuche es nicht in einer engen Schleife erneut.

Idempotente Retries

Sende Idempotency-Key bei jeder produktiven Anfrage an POST /api/v1/generations und POST /api/v1/chat/completions.

Empfohlenes Muster:

eindeutigen Key pro logischer Generation-Anfrage erzeugen
denselben Key nur beim Retry desselben Bodys wiederverwenden
die zurückgegebene öffentliche Task-ID mit deinem eigenen Job-Datensatz speichern
für Chat API die zurückgegebene session_id speichern, wenn du dieselbe Unterhaltung fortsetzen möchtest
einen Key nicht für ein anderes Modell, einen anderen Prompt oder andere Params wiederverwenden

Wenn das Netzwerk nach dem Einreichen fehlschlägt, versuche es mit demselben Body und demselben Idempotency-Key erneut. Rivya kann die gespeicherte öffentliche Antwort zurückgeben, statt einen doppelten Task zu erstellen.

Retry-Entscheidungen

Diese mit Backoff erneut versuchen:

public_api_disabled
rate_limited
internal_error
temporäre Netzwerkfehler

Diese nicht ohne geänderten Input erneut versuchen:

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-Fehler und Limits

Fehlerformat

Stabile Fehlercodes

Rate Limits

Idempotente Retries

Retry-Entscheidungen

Verwandte Seiten

Inhaltsverzeichnis