Kody błędów i ich obsługa

Rozwiązuj problemy z nieudanymi żądaniami CometAPI dzięki sprawdzonym wskazówkom dla błędów 400, 401 i ścieżek, a także praktycznym zaleceniom dotyczącym 403, 429 i błędów klasy timeout.

Obsługa błędów CometAPI jest najprostsza, gdy rozdzielisz problemy z żądaniem, problemy z autoryzacją oraz problemy platformy, które można ponowić. Ta strona jest oficjalnym przewodnikiem po błędach CometAPI i koncentruje się na tym, co możesz najpierw zweryfikować po stronie klienta.

Ten przewodnik opiera się na testach wykonanych na działającym, aktualnym API CometAPI. Bezpośrednio zweryfikowaliśmy błędy 400, 401 oraz awarie związane ze ścieżką/base URL. Nie odtworzyliśmy 413, 429, 500, 503, 504 ani 524 w kontrolowanych testach, dlatego wskazówki dla tych statusów są celowo zachowawcze.

​

Szybka diagnoza

Status	Co zwykle oznacza	Ponowić?	Pierwsze działanie
400	Walidacja żądania nie powiodła się, zanim żądanie zostało poprawnie skierowane dalej.	Nie	Zweryfikuj model, messages, strukturę JSON i typy pól.
401	Klucz API jest brakujący, nieprawidłowo sformatowany lub nieważny.	Nie	Sprawdź Authorization: Bearer <COMETAPI_KEY>.
403	Dostęp został zablokowany lub bieżące żądanie nie było dozwolone.	Zwykle nie	Ponów próbę 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 objawiać 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	Rate limiting lub tymczasowe przeciążenie.	Tak	Użyj exponential backoff z jitterem.
500, 503, 504, 524	Awaria platformy lub błąd klasy timeout.	Tak	Ponów próbę z backoff i zachowaj request id.

​

Obwiednia błędu

Aktualna obwiednia błędu JSON zwracana przez CometAPI wygląda tak:

{
	"error": {
		"code": "",
		"message": "...",
		"type": "comet_api_error"
	}
}

Wiele rzeczywistych komunikatów o błędach zawiera także request id wewnątrz error.message. Zapisz tę wartość, gdy potrzebujesz wsparcia.

​

400 Bad Request

To zaobserwowaliśmy w działającym API, gdy pominięto model:

{
	"error": {
		"code": "",
		"message": "model name is required (request id: ...)",
		"type": "comet_api_error"
	}
}

W praktyce 400 zwykle oznacza, że treść żądania nie przeszła walidacji, zanim platforma mogła skierować je do dostawcy modelu.

Najczęstsze przyczyny:

• Brak wymaganych pól, takich jak model lub messages
• 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

Co zrobić:

1. Zacznij od minimalnego, sprawdzonego żądania.
2. Dodawaj pola opcjonalne z powrotem jedno po drugim.
3. Porównaj treść żądania ze schematem endpointu w dokumentacji API.

Minimalny poprawny przykład:

{
	"model": "your-model-id",
	"messages": [
		{
			"role": "user",
			"content": "Hello"
		}
	]
}

Zastąp your-model-id dowolnym aktualnym identyfikatorem modelu ze strony CometAPI Models page.

​

401 Invalid Token

To zaobserwowaliśmy w działającym API przy nieprawidłowym kluczu:

{
	"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 ładuje starego klucza z .env, historii shella lub wdrożonego magazynu sekretów.
3. Jeśli jeden klucz nie działa, a inny działa dla tego samego żądania, traktuj to jako problem z tokenem, a nie problem z endpointem.

​

403 Forbidden

Nie odtworzyliśmy stabilnego 403 w testach ograniczonych, więc nie należy traktować pojedynczego starego szablonu komunikatu jako pełnego obrazu sytuacji.

W aktualnej dokumentacji Comet 403 jest najczęściej omawiane jako jedna z poniższych sytuacji:

• Żądanie jest blokowane przez regułę po stronie platformy, taką jak filtrowanie WAF
• Token lub route nie mają uprawnień do użycia żądanego model lub kształtu żądania
• Wybrany model odrzuca jeden z zaawansowanych parametrów, które przekazano

Co zrobić najpierw:

1. Ponów próbę z bardzo prostym żądaniem tekstowym dla model, o którym wiadomo, że działa poprawnie.
2. Usuń pola zaawansowane i parametry specyficzne dla dostawcy, a następnie dodawaj je stopniowo z powrotem.
3. Jeśli odpowiedź zawiera request id, zachowaj je przed skontaktowaniem się 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. Praktycznym rozwiązaniem nadal jest najpierw zweryfikowanie tokena, model i kształtu żądania.

​

Nieprawidłowy Base URL lub nieprawidłowa ścieżka

To obszar, w którym stara strona była najmniej dokładna.

W testach na żywo względem aktualnych endpointów Comet:

• Wysłanie żądania do https://api.cometapi.com/chat/completions zwróciło przekierowanie 301 do https://www.cometapi.com/chat/completions
• Wysłanie żądania do fałszywej ścieżki API, takiej jak https://api.cometapi.com/v1/not-a-real-endpoint, również zwróciło przekierowanie 301 do https://www.cometapi.com/v1/not-a-real-endpoint

To oznacza, że błąd w ścieżce może objawiać się jako:

• Przekierowanie
• Odpowiedź HTML inna niż JSON, jeśli klient podąża za przekierowaniami
• Błąd parsowania wewnątrz SDK
• Żądanie, które nigdy nie dociera poprawnie do warstwy API

Użyj dokładnie tego base URL:

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

Nie odtworzyliśmy 413 w teście ograniczonym, nawet przy zbyt dużym body żądania JSON o rozmiarze 8 MiB, więc stare wyjaśnienie, że prompt był zbyt długi, było zbyt wąskie.

Jeśli jednak zobaczysz 413, traktuj to przede wszystkim jako problem z rozmiarem żądania. Typowe podejrzane elementy to:

• Duże ładunki base64
• Zbyt duże obrazy lub audio osadzone inline
• Bardzo duże body 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

Nie odtworzyliśmy 429 podczas ograniczonej próby współbieżności obejmującej 24 równoległe żądania GET /v1/models, więc dokładny próg wyraźnie zależy od route, model i aktualnego stanu platformy.

Traktuj 429 jako błąd, po którym można ponowić próbę:

1. Użyj exponential backoff z jitter.
2. Zmniejsz współbieżność nagłych serii żądań.
3. Pozostaw włączone logowanie żądań, aby zobaczyć, który route i model jako pierwsze osiągają nasycenie.

Aby zobaczyć wzorzec ponawiania prób wielokrotnego użytku, sprawdź przykład backoff na stronie Chat Completions.

​

500, 503, 504, I 524

Nie odtworzyliśmy tych statusów w testach ograniczonych. Powinny być dokumentowane jako błędy po stronie serwera lub klasy timeout, a nie jako błędy użytkownika.

Praktyczne wskazówki:

• 500: wewnętrzna awaria platformy lub błąd po stronie dostawcy
• 503: route lub usługa dostawcy są tymczasowo niedostępne
• 504 i 524: błędy klasy timeout między platformą, edge lub usługą dostawcy

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 kolejnych próbach, skontaktuj się ze wsparciem, przekazując ten kontekst.

​

Zanim skontaktujesz się z pomocą techniczną

Najpierw zbierz te informacje:

• Metoda HTTP
• Ścieżka endpointu
• Nazwa modelu
• Zanonimizowany JSON request body (to najprzydatniejszy pojedynczy element dla większości wywołań API)
• Parametry zapytania, jeśli nieudane żądanie ich używało
• Dokładna treść response body, jeśli klient ją 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 problematyczna trasa 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

Najszybszym sposobem na odtworzenie błędu jest dokładny zanonimizowany request payload. Dla większości wywołań API oznacza to surowy JSON request body. Dla tras z przesyłaniem plików oznacza to listę pól oraz metadane pliku.

To znacząco skraca czas oczekiwania na odpowiedź wsparcia.