Błędy i ponawianie prób
Należy odczytywać status HTTP razem z treścią błędu w formacie JSON. Zachowaj każdy identyfikator żądania lub referencyjny zwrócony przez usługę; pozwala to działowi wsparcia znaleźć pasujący rekord bez otrzymywania promptu lub pełnego klucza.
Kody statusu
| Kod | Znaczenie | Działanie |
|---|---|---|
400 | Nieprawidłowy JSON, pole, parametr lub odrzucone żądanie | Popraw żądanie; nie ponawiaj go bez zmian |
401 | Brakujący, nieprawidłowy, wygasły lub unieważniony klucz | Sprawdź Authorization: Bearer <key> i docelowe środowisko |
402 | Saldo klucza nie pokrywa ceny zadania (analityka firmy, wideo) | Doładuj saldo, a następnie wyślij żądanie ponownie |
403 | Konto lub klucz nie może używać żądanego produktu lub ścieżki | Sprawdź GET /v1/models i włączone produkty na koncie |
404 | Nieprawidłowa ścieżka lub niedostępny zasób | Sprawdź aktualną dokumentację i identyfikator |
413 | Treść żądania jest zbyt duża | Zmniejsz lub podziel dane wejściowe |
422 | Obsługiwana ścieżka odrzuciła przesłaną strukturę | Zapoznaj się z problemami i popraw treść |
429 | Osiągnięto limit żądań, przepustowości lub konta albo budżet klucza został wykorzystany | Poczekaj i ponów próbę ze wzrastającym opóźnieniem; jeśli budżet został wykorzystany, najpierw doładuj saldo |
500, 502, 503 | Tymczasowy problem po stronie usługi | Ponów próbę ograniczoną liczbę razy, a następnie skontaktuj się z pomocą techniczną |
Wyjątkiem jest API zadań obrazu (/api/v1/jobs/*): odpowiada ono statusem HTTP 200
i umieszcza kod w ciele odpowiedzi, {"code": 422, "msg": "…", "data": null}. Zobacz
Generowanie obrazów.
Zasady ponawiania prób
Ponawiaj próby tylko w przypadku odpowiedzi 429, tymczasowych odpowiedzi 5xx i przejściowych błędów sieciowych. Użyj małej maksymalnej liczby prób, całkowitego limitu czasu (timeout), rosnących opóźnień, takich jak 1, 2 i 4 sekundy, oraz niewielkiej losowej wariacji, gdy wiele procesów roboczych może ponawiać próby jednocześnie.
Nie ponawiaj niezmienionego żądania, które zwróciło błąd 400, 401, 402, 403, 404, 413 lub 422. Przerwane połączenie wymaga ostrożności: żądanie mogło już zostać zakończone i zużyć środki, więc automatyczny duplikat może wygenerować dodatkową pracę i koszty.
Co należy logować
Rejestruj przybliżony czas i strefę czasową, model publiczny, ścieżkę, status, identyfikator żądania lub referencyjny oraz alias klucza, jego prefiks lub ostatnie cztery znaki. Nigdy nie loguj ani nie wysyłaj pełnego klucza, haseł, poufnych promptów, śladów stosu (stack traces) ani nazw wewnętrznych.
Jeśli ograniczona liczba ponowień nadal kończy się niepowodzeniem, skontaktuj się z support@omev.be, podając oczyszczony przykład i zarejestrowane identyfikatory.