FAQ

Rozwiązywanie problemów

Rozwiązuj problemy z uwierzytelnianiem, modelami, strumieniowaniem, zadaniami i limitami zapytań według objawów.

Zacznij od objawu, a następnie przejdź do rozwiązania. Większość niepowodzeń wynika z bazowego adresu URL, klucza, identyfikatora modelu lub salda.

Tabela objawów

Objaw	Prawdopodobna przyczyna	Rozwiązanie
401 `UNAUTHORIZED`	Brakujący, błędny, unieważniony lub niewysłany klucz	Wyślij `Authorization: Bearer $FELO_API_KEY`; utwórz nowy klucz, jeśli został unieważniony
402 `INSUFFICIENT_CREDITS`	Saldo nie pokrywa wywołania	Doładuj w Console Billing
404 przy każdym żądaniu	Bazowy adres URL zawiera ścieżkę, którą endpoint już dodaje	Użyj `https://openapi.felo.ai/api/v1` dla klientów OpenAI i `https://openapi.felo.ai/api` dla klientów Anthropic
404 przy jednym modelu	Identyfikator modelu nie jest publiczny lub endpoint go nie obsługuje	Sprawdź identyfikator modelu na stronie modeli i w dokumentacji endpointu
400 błąd `model` lub `max_tokens`	Brak wymaganego pola lub model nie akceptuje kształtu żądania	Dodaj `max_tokens` dla Messages; usuń nieobsługiwane pola
429	Limit szybkości lub limit dostawcy upstream	Odczytaj `Retry-After`; zobacz Błędy, limity i ponawianie
5xx	Niepowodzenie upstream lub usługi	Ponów z wykładniczym opóźnieniem; dołącz `request_id`, jeśli problem się utrzymuje
Strumień łączy się, ale nic nie wysyła	Proxy buforuje odpowiedź lub parser zdarzeń oczekuje niewłaściwego formatu	Odczytuj strumień przyrostowo; wyłącz buforowanie odpowiedzi w proxy
Zadanie nigdy się nie kończy	Niewłaściwy endpoint odpytania lub nieobsłużony stan terminalny	Odpytuj endpoint stanu samego zadania i zatrzymuj się na wartościach terminalnych
Wywołania narzędzi są ignorowane	Model nie deklaruje tej możliwości	Sprawdź `supported_parameters` w katalogu
Data API zwraca 404	Prefiks `/v1/beta` został dodany dwukrotnie	Użyj ścieżki dokładnie tak, jak zapisano ją w dokumentacji

Uwierzytelnianie

Unieważniony klucz zwraca komunikat zawierający prefiks klucza:

{
  "status": 401,
  "code": "UNAUTHORIZED",
  "message": "API Key has been revoked (keyPrefix=...)"
}

Lista kontrolna:

Nagłówek ma postać Authorization: Bearer <key> dla Model API i Felo APIs.
Data API akceptuje też X-API-Key: <key>.
Klucz nie jest ujęty w cudzysłowie i nie ma na końcu znaku nowej linii ze skopiowanej zmiennej środowiskowej.
Wdrożone środowisko rzeczywiście ma ustawioną zmienną; klucz działający lokalnie może być nieobecny w produkcji.
Klucz nie został usunięty ani zrotowany. Usuniętego lub zrotowanego klucza nie można ponownie wyświetlić; utwórz nowy.

Tworzenie kluczy i limity znajdziesz w Uwierzytelnianiu.

Pułapki bazowego adresu URL

Klient	Prawidłowy bazowy adres URL
OpenAI SDK	`https://openapi.felo.ai/api/v1`
Anthropic SDK	`https://openapi.felo.ai/api`
Surowy endpoint modelu	`https://openapi.felo.ai/api/v1/chat/completions`, `/responses` lub `/messages`
Data API	`https://openapi.felo.ai/v1/beta`
Felo `/v2` APIs	`https://openapi.felo.ai/v2`

Dwa typowe błędy:

Dodawanie /chat/completions do bazowego adresu URL, który SDK już rozszerza.
Ustawianie bazowego adresu URL Anthropic na https://openapi.felo.ai/api/v1. SDK dopisuje /v1/messages, więc żądanie trafia na /api/v1/v1/messages.

Problemy z identyfikatorem modelu

Identyfikatory modeli to publiczne identyfikatory z katalogu, a nie wewnętrzne nazwy dostawcy upstream ani nazwa wyświetlana.

Sprawdź identyfikator na stronie modeli lub w GET /api/v1/models.
Potwierdź, że model obsługuje protokół, który wywołujesz (supported_protocols).
Jeśli przypiąłeś kanał, potwierdź, że jest on opublikowany i uruchamialny dla tego modelu. Niedostępny kanał nie jest mechanizmem awaryjnym.

Zobacz Kanały i routing dostawców.

Problemy z przesyłaniem strumieniowym

Ustaw stream: true w treści żądania, a nie jako parametr zapytania.
Odczytuj treść odpowiedzi jako strumień. Czekanie na pełną odpowiedź niweczy przesyłanie strumieniowe.
Niektóre proxy i platformy serverless buforują odpowiedzi. Wyłącz buforowanie dla trasy, która pośredniczy w żądaniu.
Chat Completions przesyła strumieniowo choices[0].delta, a nie choices[0].message. Końcowa treść przychodzi w wielu fragmentach.
Strumień może zakończyć się bez czystego zdarzenia terminalnego, jeśli połączenie zostanie zerwane. Traktuj zerwane połączenie jako niekompletną odpowiedź.

Problemy z zadaniami asynchronicznymi

Odpytuj endpoint stanu należący do danej rodziny zadań. Przepływy Felo używają GET /v2/tasks/{task_id}/status; zadania wideo i obrazów modeli używają własnych endpointów generowania.
Zatrzymuj się przy każdym stanie terminalnym, w tym przy niepowodzeniach i wygaśnięciach, nie tylko przy powodzeniu.
Wywołania zwrotne wideo i obrazów są obecnie ignorowane. Nie czekaj na webhook.
Adres URL wyniku może być krótkotrwały. Jeśli pobieranie wygaśnie, poproś o nowy adres URL w endpointcie stanu.
Sprawdź zadanie przed ponownym wysłaniem. Ponowne wysłanie działającego zadania tworzy duplikat, a oba są rozliczane.

Zobacz Zadania asynchroniczne.

Problemy z Data API

Zachowaj dokładną ścieżkę metody z dokumentacji Data API.
Treści żądań są specyficzne dla dostawcy. Pole działające u jednego dostawcy nie musi działać u innego.
Błąd dostawcy może przyjść w odpowiedzi 4xx z komunikatem specyficznym dla dostawcy. Zapisuj w logach request_id i treść odpowiedzi.

Przypomnienia o bezpieczeństwie

Nigdy nie umieszczaj klucza API w kodzie przeglądarki, pakiecie aplikacji mobilnej ani publicznym repozytorium. Trzymaj go na serwerze i pośrednicz w żądaniach.
Nie zapisuj w logach pełnego klucza. Jeśli musisz go zidentyfikować, zapisz prefiks.
Natychmiast zrotuj klucz, jeśli mógł wyciec.

Przed kontaktem z pomocą techniczną

Zbierz:

Endpoint i metodę HTTP.
Status HTTP, code i request_id.
Identyfikator modelu lub zadania.
Znacznik czasu ze strefą czasową.
Minimalną treść żądania z usuniętymi sekretami.

Wyślij je do pomocy technicznej wraz z adresem e-mail konta. Nie dołączaj pełnego klucza API.