Obsługa błędów CometAPI jest najprostsza, gdy rozdzielisz problemy ze strukturą żądania, problemy z uwierzytelnianiem, błędy ścieżki oraz błędy platformy, które można ponowić. Użyj kombinacji statusu HTTP, error.code i error.message, aby zdecydować, czy poprawić żądanie, czy je ponowić.
Szybka diagnoza
Obudowa błędu
Wiele błędów CometAPI używa treści błędu podobnej do tej:
Niektóre odpowiedzi pozostawiają code puste. Gdy status to 500, traktuj error.code i error.message jako sygnał decydujący.
400 Bad Request
400 zwykle oznacza, że treść żądania nie przeszła walidacji, zanim żądanie mogło zostać normalnie przetworzone.
Typowe przyczyny:
- Brak wymaganych pól, takich jak
model
- Nieprawidłowa struktura JSON
- Wysłanie pola z nieprawidłowym typem
- Ponowne użycie parametrów specyficznych dla dostawcy, których wybrany endpoint nie akceptuje
Zacznij od minimalnego, sprawdzonego żądania, a następnie dodawaj z powrotem pola opcjonalne jedno po drugim. Porównaj payload ze schematem endpointu w dokumentacji API.
Użyj minimalnego żądania takiego jak to:
Zastąp your-model-id dowolnym aktualnym model ID ze strony CometAPI Models page.
Nie zakładaj, że każde nieprawidłowo sformułowane żądanie czatu zwraca 400. Brak wymaganych pól czatu, takich jak messages, może również pojawić się jako 500 z error.code: invalid_request.
500 Internal Server Error
Większość odpowiedzi 500 wskazuje na błąd platformy lub dostawcy. W przypadku Chat Completions niektóre nieprawidłowo sformułowane żądania mogą również pojawić się jako 500, nadal zawierając error.code: invalid_request.
Jednym z przykładów jest żądanie, które pomija messages:
Jeśli odpowiedź 500 ma error.code: invalid_request, traktuj ją jako problem z żądaniem:
- Popraw treść żądania.
- Porównaj payload ze schematem endpointu.
- Ponów dopiero po poprawieniu payload.
Jeśli odpowiedź 500 nie wskazuje na nieprawidłowe żądanie, zachowaj request id i użyj backoff.
401 Invalid Token
Błąd tokenu zwykle wygląda tak:
Co sprawdzić:
- Nagłówek musi mieć dokładnie postać
Authorization: Bearer $COMETAPI_KEY.
- Upewnij się, że Twoja aplikacja nie wczytuje starego klucza z
.env, historii shella ani z wdrożonego magazynu sekretów.
- Jeśli jeden klucz nie działa, a inny działa dla tego samego żądania, potraktuj to jako problem z tokenem, a nie z endpointem.
403 Forbidden
403 najczęściej oznacza jedną z tych sytuacji:
- Żądanie jest blokowane przez regułę po stronie platformy, taką jak filtrowanie WAF
- Token lub trasa nie mają uprawnień do użycia żądanego modelu albo kształtu żądania
- Wybrany model odrzuca jeden z przekazanych zaawansowanych parametrów
Co zrobić najpierw:
- Ponów próbę z bardzo prostym żądaniem tekstowym względem znanego, działającego modelu.
- Usuń zaawansowane pola i parametry specyficzne dla providera, a następnie dodawaj je z powrotem stopniowo.
- Jeśli odpowiedź zawiera request id, zachowaj je przed kontaktem ze wsparciem.
Jeśli komunikat wspomina o wewnętrznych terminach takich jak group lub channel, traktuj je jako szczegóły routingu, a nie jako pierwszą rzecz do diagnozowania po stronie klienta. W praktyce nadal należy najpierw zweryfikować token, model i kształt żądania.
Wrong base URL or wrong path
W Comet błąd ścieżki może objawiać się jako:
- Przekierowanie
- Odpowiedź HTML zamiast JSON, jeśli klient podąża za przekierowaniami
- Błąd parsowania wewnątrz Twojego SDK
- Żądanie, które nigdy nie dociera poprawnie do warstwy API
Użyj dokładnie tego base URL:
Zalecane kontrole:
- Potwierdź, że base URL zawiera
/v1.
- Potwierdź, że ścieżka endpointu dokładnie odpowiada dokumentacji.
- Wyłącz automatyczne podążanie za przekierowaniami podczas debugowania problemów ze ścieżką.
413 Request Entity Too Large
Jeśli widzisz 413, najpierw potraktuj to jako problem z rozmiarem żądania. Częste przyczyny to:
- Duże payloady base64
- Zbyt duże obrazy lub audio osadzone inline
- Bardzo duże treści multipart lub JSON
Co zrobić:
- Zmniejsz lub skompresuj dołączoną zawartość.
- Podziel duże zadania na mniejsze żądania.
- Nie zakładaj, że jedyną przyczyną jest długość zwykłego tekstu.
429 Too Many Requests
429 należy traktować jako błąd, po którym można ponowić próbę:
- Użyj exponential backoff z jitter.
- Ogranicz burst concurrency.
- Pozostaw włączone logowanie żądań, aby zobaczyć, która trasa i który model nasycają się jako pierwsze.
Aby użyć gotowego wzorca ponawiania prób, zobacz przykład backoff w Chat Completions.
503, 504, and 524
Te statusy oznaczają błędy po stronie serwera lub błędy klasy timeout.
Praktyczne wskazówki:
503: trasa lub usługa providera są tymczasowo niedostępne504 i 524: błędy klasy timeout między platformą, edge lub usługą providera
Co zrobić:
- Ponów próbę z backoff.
- Zachowaj
request id, endpoint, model i znacznik czasu.
- Jeśli ten sam błąd powtarza się przy wielu ponowieniach, skontaktuj się ze wsparciem, przekazując ten kontekst.
Zanim skontaktujesz się ze wsparciem
Najpierw zbierz te informacje:
- Metoda HTTP
- Ścieżka endpointu
- Model ID
- Zanonimizowany JSON body żądania (to najprzydatniejszy pojedynczy element dla większości wywołań API)
- Parametry zapytania, jeśli nieudane żądanie ich używało
- Dokładny response body, jeśli Twój klient go przechwycił
- Pełny status HTTP
- Dokładne
error.message
- Dowolny
request id
- Przybliżony znacznik czasu
- Czy to samo żądanie działa z innym modelem lub innym tokenem
Jeśli trasa, która zwraca błąd, akceptuje przesyłanie plików (edycja obrazów, przesyłanie audio, generowanie wideo itp.) zamiast zwykłego JSON body, wyślij równoważny przesłany payload:
- Nazwy pól i wartości tekstowe wysłane razem z plikiem
- Nazwa pliku, typ pliku i przybliżony rozmiar pliku
- Czy plik został przesłany bezpośrednio, wskazany przez URL czy osadzony jako base64
Najskuteczniejszym sposobem odtworzenia błędu jest dokładny zanonimizowany payload żądania. Dla większości wywołań API oznacza to surowy JSON body żądania. Dla tras z przesyłaniem plików oznacza to listę pól oraz metadane pliku.
