> ## Documentation Index > Fetch the complete documentation index at: https://apidoc.cometapi.com/llms.txt > Use this file to discover all available pages before exploring further. # Obsługa kodów błędów > Skorzystaj z tego przewodnika, aby klasyfikować odpowiedzi błędów CometAPI i stosować ponowienia lub kroki naprawcze dla typowych niepowodzeń żądań. 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 | Status | Co zwykle oznacza | Ponowić? | Pierwsze działanie | | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------- | | `400` | Walidacja żądania nie powiodła się, zanim żądanie zostało normalnie przetworzone. | Nie | Zweryfikuj `model`, `messages`, strukturę JSON i typy pól. | | `401` | Klucz API jest brakujący, niepoprawnie sformatowany lub nieprawidłowy. | Nie | Sprawdź `Authorization: Bearer $COMETAPI_KEY`. | | `403` | Dostęp został zablokowany lub bieżące żądanie nie było dozwolone. | Zwykle nie | Ponów z poprawnym, sprawdzonym żądaniem i najpierw usuń pola specyficzne dla modelu. | | Błąd ścieżki | Nieprawidłowy base URL lub nieprawidłowa ścieżka endpointu. W Comet może to pojawić się jako przekierowanie `301` lub HTML, a nie czysty JSON `404`. | Nie | Użyj dokładnie `https://api.cometapi.com/v1` i wyłącz automatyczne podążanie za przekierowaniami podczas debugowania. | | `429` | Ograniczanie szybkości lub tymczasowe przeciążenie. | Tak | Użyj exponential backoff z jitter. | | `500` with `error.code: invalid_request` | Nieprawidłowo sformułowane żądanie zwrócone w odpowiedzi ze statusem serwera. | Nie | Popraw treść żądania przed ponowieniem. | | `500`, `503`, `504`, `524` | Błąd platformy, dostawcy lub klasy timeout. | Tak | Ponów z backoff i zachowaj identyfikator żądania. | ## Obudowa błędu Wiele błędów CometAPI używa treści błędu podobnej do tej: ```json theme={null} { "error": { "message": "...", "type": "comet_api_error", "param": "", "code": "invalid_request" } } ``` 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: ```json theme={null} { "model": "your-model-id", "messages": [ { "role": "user", "content": "Hello" } ] } ``` Zastąp `your-model-id` dowolnym aktualnym model ID ze strony [CometAPI Models page](/pl/overview/models). 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`: ```json theme={null} { "error": { "message": "field messages is required (request id: ...)", "type": "comet_api_error", "param": "", "code": "invalid_request" } } ``` Jeśli odpowiedź `500` ma `error.code: invalid_request`, traktuj ją jako problem z żądaniem: 1. Popraw treść żądania. 2. Porównaj payload ze schematem endpointu. 3. 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: ```json theme={null} { "error": { "code": "", "message": "invalid token (request id: ...)", "type": "comet_api_error" } } ``` Co sprawdzić: 1. Nagłówek musi mieć dokładnie postać `Authorization: Bearer $COMETAPI_KEY`. 2. Upewnij się, że Twoja aplikacja nie wczytuje starego klucza z `.env`, historii shella ani z wdrożonego magazynu sekretów. 3. 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: 1. Ponów próbę z bardzo prostym żądaniem tekstowym względem znanego, działającego modelu. 2. Usuń zaawansowane pola i parametry specyficzne dla providera, a następnie dodawaj je z powrotem stopniowo. 3. 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: ```text theme={null} https://api.cometapi.com/v1 ``` Zalecane kontrole: 1. Potwierdź, że base URL zawiera `/v1`. 2. Potwierdź, że ścieżka endpointu dokładnie odpowiada dokumentacji. 3. 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ć: 1. Zmniejsz lub skompresuj dołączoną zawartość. 2. Podziel duże zadania na mniejsze żądania. 3. 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ę: 1. Użyj exponential backoff z jitter. 2. Ogranicz burst concurrency. 3. 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](/api/text/chat). ## `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ępne * `504` i `524`: błędy klasy timeout między platformą, edge lub usługą providera Co zrobić: 1. Ponów próbę z backoff. 2. Zachowaj `request id`, endpoint, model i znacznik czasu. 3. 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. To znacząco skraca czas odpowiedzi wsparcia.