Błędy, limity i ponawianie

Każde API Felo zwraca treść błędu JSON ze stabilnym kodem błędu i identyfikatorem żądania. Najpierw odczytaj status HTTP, potem kod, a na końcu komunikat.

Koperta błędów

Obecne odpowiedzi produkcyjne używają statusu HTTP jako status:

{
  "status": 401,
  "code": "UNAUTHORIZED",
  "message": "Invalid API Key",
  "request_id": "202610221444486982113280416060637185"
}

Niektóre starsze przykłady endpointów używają status: "error" i innego ciągu kodu. Rozgałęziaj logikę na podstawie statusu HTTP i pola code, a nie dokładnego brzmienia message.

Typowe kody

Dokumentacja endpointów wymienia kody specyficzne dla danego endpointu. Zacznij od błędów API Chat lub dokumentacji endpointu, który wywołujesz.

Endpointy generowania modeli

POST /api/v1/images/generations i POST /api/v1/videos/generations zwracają błędy na poziomie endpointu w kopercie OpenAI zamiast koperty opisanej powyżej:

{
  "error": {
    "message": "Model kind does not match this generation endpoint",
    "type": "invalid_request_error",
    "param": null,
    "code": "model_kind_mismatch"
  }
}

Identyfikator żądania znajduje się w nagłówku odpowiedzi X-Request-Id, a nie w treści. Odrzucone żądanie nie tworzy zadania. Gdy zadanie już istnieje, większość niepowodzeń przychodzi jako terminalny stan zadania w odpowiedzi 200, a nie jako błąd HTTP: sprawdź, czy status ma wartość failed lub interrupted, a następnie odczytaj error.message. Zobacz Generowanie obrazów i Zadania asynchroniczne.

Identyfikatory żądań

Treści błędów Felo zawierają request_id. Zapisuj go w logach wraz z endpointem, statusem HTTP, kodem błędu, identyfikatorem modelu i identyfikatorem zadania. Nigdy nie zapisuj w logach pełnego klucza API.

Model API przyjmuje też opcjonalny nagłówek żądania X-Request-Id. Gdy go wyślesz, jest odsyłany z powrotem do celów diagnostycznych, co pozwala skorelować własne logi z żądaniem. Jeśli go nie wyślesz, użyj zwróconego request_id.

Limity szybkości

/v2/chat to jedyny endpoint Felo z udokumentowanymi, egzekwowanymi limitami szybkości:

• na klucz API, okno 1 minuty.
• na użytkownika, okno 1 minuty.
• na użytkownika, okno 1 godziny.

Użytkownicy z aktywną płatną subskrypcją Felo, w tym subskrypcją enterprise, są zwolnieni i nie otrzymują nagłówków X-RateLimit-*. Jeśli nie można zweryfikować statusu subskrypcji, limity nadal obowiązują.

Inne endpointy /v2/** nie mają obecnie egzekwowanych limitów szybkości. Żądania do Model API nadal mogą być ograniczane przez dostawcę upstream, co może pojawić się jako 429.

Nie wpisuj w kodzie na stałe wartości liczbowych limitów. Odczytuj nagłówki każdej odpowiedzi.

Zasady ponawiania

Zalecana pętla:

1. Ponawiaj tylko żądania idempotentne lub bezpieczne do powtórzenia.
2. Stosuj wykładnicze opóźnienie: zacznij od około 1 sekundy, podwajaj je, ogranicz do 30 sekund.
3. Dodaj losowe odchylenie, aby klienci nie ponawiali równocześnie.
4. Zatrzymaj się po niewielkiej liczbie prób i zgłoś błąd.
5. Przy 429 przestrzegaj Retry-After zamiast własnego harmonogramu.

Sekwencja debugowania

1. Sprawdź, czy klucz istnieje i nie został unieważniony.
2. Wywołaj GET /api/v1/models z tym samym kluczem, aby potwierdzić uwierzytelnianie.
3. Wyślij najmniejsze prawidłowe żądanie do docelowego endpointu.
4. Dodawaj przesyłanie strumieniowe, narzędzia lub duże dane wejściowe pojedynczo.
5. W przypadku pracy asynchronicznej sprawdź stan zadania przed ponownym wysłaniem.

Powiązane

• Uwierzytelnianie
• Kanały i routing dostawców
• Zadania asynchroniczne
• Rozwiązywanie problemów