Obsługuj publiczne kody błędów Rivya API, statusy HTTP, limity szybkości, konflikty idempotencji i decyzje o ponowieniu.

Rivya API zwraca stabilne publiczne kody błędów w JSON. Traktuj wartość error.code jako kontrakt integracyjny.

Kształt Błędu

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

Zachowuj requestId w swoich logach, gdy prosisz wsparcie Rivya o zbadanie nieudanego żądania API.

Stabilne Kody Błędów

Code	HTTP status	Znaczenie	Sugerowane działanie
`public_api_disabled`	503	Wywołania Public API są tymczasowo wyłączone.	Ponów później albo użyj Studio ręcznie.
`api_key_missing`	401	Żądanie nie zawierało klucza Bearer API.	Wyślij `Authorization: Bearer rvya_sk_...`.
`api_key_invalid`	401	Klucza nie można zweryfikować.	Sprawdź klucz i w razie potrzeby go obróć.
`api_key_revoked`	401	Klucz został unieważniony w Ustawieniach.	Utwórz nowy klucz.
`api_key_expired`	401	Klucz nie jest już ważny.	Utwórz nowy klucz.
`api_scope_denied`	403	Klucz nie ma wymaganego zakresu.	Utwórz klucz z potrzebnym zakresem.
`rate_limited`	429	Zbyt wiele żądań w bieżącym oknie.	Wycofaj tempo i ponów później.
`validation_failed`	400	Body, model, prompt albo parametry są nieprawidłowe.	Porównaj body z referencją modelu.
`not_found`	404	Żądane zadanie nie istnieje albo nie należy do tego konta.	Sprawdź publiczny ID zadania i granicę konta.
`webhook_url_rejected`	400	URL endpointu webhooka jest niedozwolony.	Użyj publicznego URL HTTPS bez poświadczeń, fragmentów, localhost ani adresów sieci prywatnej.
`chat_model_not_supported`	400	Wybrany model nie jest dostępny dla Chat API.	Odczytaj `/api/v1/models` i wybierz dostępny model czatu.
`chat_session_conflict`	409	Sesji czatu nie można użyć dla tego żądania.	Użyj sesji utworzonej przez API, należącej do tego samego konta i modelu.
`chat_attachment_not_supported`	400	Załącznik czatu nie jest obsługiwany.	Prześlij obraz przez Files API i przekaż jego `file_id`.
`idempotency_conflict`	409	Ten sam klucz idempotencji został ponownie użyty z innymi danymi wejściowymi.	Użyj nowego klucza albo wyślij ponownie dokładnie to samo body.
`insufficient_credits`	402	Konto nie ma wystarczającej liczby kredytów.	Dodaj kredyty albo wybierz żądanie o niższym koszcie.
`internal_error`	500	Żądania nie udało się ukończyć.	Ponów z idempotencją albo skontaktuj się ze wsparciem, podając `requestId`.

Limity Szybkości

Rivya stosuje limity szybkości Public API na poziomie aplikacji dla każdego klucza API. Domyślny limit produkcyjny jest konfigurowany przez PUBLIC_API_RATE_LIMIT_PER_MINUTE.

Gdy otrzymasz rate_limited, użyj wykładniczego backoffu. Nie ponawiaj żądań w ciasnej pętli.

Idempotentne Ponowienia

Wysyłaj Idempotency-Key z każdym produkcyjnym żądaniem POST /api/v1/generations i POST /api/v1/chat/completions.

Zalecany wzorzec:

generuj unikalny klucz dla każdego logicznego żądania generowania
używaj ponownie tego samego klucza tylko przy ponawianiu tego samego body
zapisuj zwrócony publiczny ID zadania przy własnym rekordzie zadania
dla Chat API zapisuj zwrócone session_id, gdy chcesz kontynuować tę samą rozmowę
nie używaj jednego klucza dla innego modelu, promptu albo parametrów

Jeśli sieć zawiedzie po wysłaniu, ponów z tym samym body i tym samym Idempotency-Key. Rivya może zwrócić zapisaną publiczną odpowiedź zamiast tworzyć duplikat zadania.

Decyzje o Ponowieniu

Te błędy ponawiaj z backoffem:

public_api_disabled
rate_limited
internal_error
tymczasowe awarie sieci

Nie ponawiaj tych błędów bez zmiany danych wejściowych:

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

Błędy i limity API

Kształt Błędu

Stabilne Kody Błędów

Limity Szybkości

Idempotentne Ponowienia

Decyzje o Ponowieniu

Powiązane Strony

Spis treści