Błędy CometAPI 401, 404, 429 i 5xx: ponowić próbę czy zakończyć?

Krótka odpowiedź: nie przełączaj się z Claude na GPT przy każdym nieudanym żądaniu. 401 oznacza, że trzeba naprawić uwierzytelnianie, a 404 związany ze ścieżką oznacza, że należy poprawić URL lub endpoint. 429 lub tymczasowe 5xx można ponawiać z backoffem; jeśli mimo ograniczonej liczby prób nadal się nie udaje, może przejąć zgodny model zapasowy.

Jest jeden ważny wyjątek: odpowiedź 500 z error.code: invalid_request to nadal problem z żądaniem. Ponawianie go — lub wysyłanie tej samej wadliwej treści żądania do innego modelu — jedynie maskuje błąd.

Ten artykuł zweryfikowano 20 sierpnia 2026 r. względem dokumentacji CometAPI dotyczącej błędów, ponowień, bazowego URL, limitów szybkości i fallbacku modeli. Obejmuje wyłącznie klasyfikację błędów. W kwestii projektowania tras, poświadczeń dostawców i wielowarstwowego failoveru skorzystaj z pełnego samouczka o fallbacku modeli oraz technicznego przewodnika po fallbacku.

Zacznij od decyzji: ponawiać czy zakończyć błędem

Praktyczne pytanie nie brzmi „Czy Claude zawiódł?”, lecz „Czy inny model mógłby się udać bez zmiany nieprawidłowej części tego żądania?”. Błędy uwierzytelniania i ścieżki dotyczą samego połączenia, więc zmiana modelu ich nie rozwiąże. Tymczasowe problemy z pojemnością i awarie serwera mogą być specyficzne dla trasy, więc fallback może pomóc.

Przeczytaj błąd, zanim zmienisz model

Użyj statusu HTTP wraz z error.code i error.message. Wiele błędów CometAPI używa koperty jak poniżej:

{
  "error": {
    "message": "human-readable detail and request id",
    "type": "comet_api_error",
    "param": "problematic_parameter_or_empty",
    "code": "error_code_or_empty"
  }
}

Nie klasyfikuj tylko po pierwszej cyfrze kodu statusu. 500 może nadal nieść invalid_request, podczas gdy nieprawidłowa ścieżka CometAPI może zwrócić przekierowanie lub HTML zamiast czystego JSON-owego 404.

401 Unauthorized: zatrzymaj się i napraw uwierzytelnianie

401 zwykle oznacza, że klucz API jest brakujący, zniekształcony, wygasł lub załadowany z niewłaściwego środowiska. Nagłówek musi wyglądać tak:

Authorization: Bearer $COMETAPI_KEY

Nie ponawiaj i nie zmieniaj modelu. Obie trasy będą używać tego samego błędnego uwierzytelniania. Sprawdź, czy wdrożona usługa nie załadowała starego sekretu, czy do klucza nie dodano białych znaków i czy żądanie trafia do zamierzonego środowiska. Rotuj lub przeładuj klucz wyłącznie poprzez wasz system zarządzania sekretami.

404 Not Found: napraw URL przed fallbackiem

Dla żądań zgodnych z OpenAI użyj dokładnie tego bazowego URL:

https://api.cometapi.com/v1

Brak /v1, zduplikowany segment ścieżki lub niewłaściwy endpoint mogą spowodować 404, przekierowanie, odpowiedź HTML lub błąd parsowania w SDK. Wyłącz automatyczne podążanie za przekierowaniami podczas debugowania i potwierdź finalną ścieżkę żądania względem referencji API.

Jeśli odpowiedź explicite mówi, że model jest niedostępny lub nie znaleziono go, zweryfikuj identyfikator modelu w aktualnym CometAPI Models API. Nie traktuj każdego 404 jako niedostępności modelu. Dodaj fallback specyficzny dla modelu dopiero po przechwyceniu i przetestowaniu dokładnie tego sygnału.

429 Too Many Requests: zastosuj backoff zanim przełączysz się na model zapasowy

429 nadaje się do ponawiania. Zastosuj wykładniczy backoff z jitterem, zmniejsz chwilowe skoki współbieżności i zmierz, która trasa się nasyca. Natychmiastowe ponowienie przez każdego worker-a może zamienić krótki limit w większy skok ruchu.

Po niewielkiej, ograniczonej liczbie prób fallback może być właściwy, gdy następny model wspiera ten sam kontrakt wejścia/wyjścia i wymagane możliwości. Fallback nie jest darmowy: zwiększa opóźnienie i może zmienić koszt lub zachowanie, więc rejestruj, jak często jest używany.

Błędy 5xx: sprawdź kod, potem ponów

500, 503, 504 i 524 zazwyczaj oznaczają awarie platformy, dostawcy lub klasy timeout. Zachowaj identyfikator żądania, endpoint, model i znacznik czasu, potem ponów z backoffem. Jeśli ten sam przejściowy błąd przetrwa budżet ponowień, przejdź do kolejnej zgodnej trasy.

Ale najpierw sprawdź body. Gdy 500 zawiera error.code: invalid_request lub invalid_request_error, napraw treść żądania i ponawiaj dopiero po wprowadzeniu zmian. Typowe przyczyny to brak pola messages lub parametr specyficzny dla dostawcy, którego wybrany endpoint nie akceptuje.

Użyj jednej prostej polityki w kodzie

Ten przykład w Pythonie utrzymuje ponawianie i fallback w aplikacji. Używa jednego klucza CometAPI, bazowego URL zgodnego z OpenAI oraz zmiennych środowiskowych dla bieżących identyfikatorów modeli Claude i GPT. Ponawia tylko błędy przejściowe, a po wyczerpaniu budżetu ponowień zmienia model.

import os, random, time
from openai import APIError, OpenAI

client = OpenAI(
    api_key=os.environ["COMETAPI_KEY"],
    base_url="https://api.cometapi.com/v1",
    max_retries=0,
)
MODELS = [os.environ["CLAUDE_MODEL"], os.environ["GPT_MODEL"]]
RETRYABLE = {429, 500, 503, 504, 524}

def complete(messages):
    for model in MODELS:
        for attempt in range(3):
            try:
                response = client.chat.completions.create(model=model, messages=messages)
                return response.choices[0].message.content
            except APIError as error:
                status = getattr(error, "status_code", None)
                code = getattr(error, "code", None)
                if status in {401, 404} or code in {
                    "invalid_request", "invalid_request_error"
                }:
                    raise
                if status not in RETRYABLE:
                    raise
                if attempt < 2:
                    time.sleep(2**attempt + random.random())
                    continue
                break
    raise RuntimeError("No configured route completed.")

print(complete([{"role": "user", "content": "Summarize this ticket."}]))

Automatyczne ponowienia w SDK są wyłączone, dzięki czemu aplikacja kontroluje całkowity budżet ponowień i fallbacków. Bez tej kontroli ponowienia SDK plus ponowienia aplikacji mogą zwielokrotnić wywołania i opóźnić finalną odpowiedź.

Przetestuj politykę bez zgadywania

To są testy polityki, a nie twierdzenia o niezawodności dostawców na żywo. W środowisku staging wstrzykuj status i body błędu do klasyfikatora, zweryfikuj liczbę i kolejność wywołań oraz potwierdź, że finalny błąd nadal zawiera kontekst oryginalnego żądania.

Kiedy fallback z Claude do GPT jest rzeczywiście bezpieczny

Przełączanie rodzin modeli jest bezpieczne tylko wtedy, gdy obie trasy potrafią spełnić ten sam kontrakt aplikacyjny. Znormalizuj pola żądania i odpowiedzi, przetestuj ustrukturyzowane wyjście lub zachowanie narzędzi na obu modelach i zweryfikuj wymagane możliwości dotyczące obrazu, dokumentów, kontekstu czy rozumowania przed włączeniem tej trasy.

Fallback powinien także respektować skutki uboczne. Jeśli pierwsza trasa już uruchomiła narzędzie, zapisała dane lub rozpoczęła strumieniowanie częściowej odpowiedzi, bezrefleksyjne powtórzenie całego żądania może zduplikować działania lub zdezorientować użytkownika. Wznów od punktu kontrolnego albo zwróć kontrolowaną porażkę.

Kontrole produkcyjne, które utrzymują ponowienia w ryzach

• Ustal jeden łączny budżet opóźnień. Każde ponowienie i fallback licz w ramach tego samego terminu.
• Ogranicz liczbę ponowień. Użyj backoffu z jitterem i zatrzymaj się po niewielkim, skonfigurowanym limicie.
• Kontroluj współbieżność. Zmniejsz skoki obciążenia zanim żądania opuszczą aplikację.
• Dodaj circuit breaker. Tymczasowo wstrzymaj wywołania do trasy, która uporczywie zawodzi.
• Loguj decyzje. Rejestruj status, kod błędu, identyfikator żądania, model, próbę, opóźnienie i powód fallbacku, nie zapisując sekretów.
• Śledź wskaźnik fallbacków. Utrzymany wzrost to sygnał operacyjny, a nie normalna metryka sukcesu.

Najczęściej zadawane pytania

Czy 401 powinien kiedykolwiek uruchamiać fallback na model zapasowy?

Nie. Napraw lub przeładuj klucz API. Inny model wywołany przez to samo nieprawidłowe poświadczenie zawiedzie z tego samego powodu.

Czy 404 powinien uruchamiać fallback?

Nie domyślnie. Najpierw napraw bazowy URL lub endpoint. Tylko osobno zweryfikowany sygnał „model niedostępny” powinien wejść do klasyfikatora fallbacku.

Ile razy powinienem ponowić 429?

Użyj niewielkiego, zdefiniowanego w aplikacji limitu mieszczącego się w budżecie opóźnień widocznym dla użytkownika. Zastosuj backoff z jitterem i zmniejsz współbieżność; nie ponawiaj natychmiast ani w nieskończoność.

Czy wszystkie błędy 5xx nadają się do ponowienia?

Nie. Tymczasowe 500, 503, 504 i 524 to kandydaci do ponowienia, ale 500 z invalid_request powinno twardo zakończyć się błędem, dopóki treść żądania nie zostanie naprawiona.

Czy Claude i GPT mogą używać tego samego żądania bez zmian?

Tylko dla wspólnych pól, które twoja aplikacja przetestowała. Parametry specyficzne dla dostawcy, formaty narzędzi, ustrukturyzowane wyjścia i wejścia multimodalne mogą wymagać adapterów. Sama zmiana identyfikatora modelu nie dowodzi kompatybilności.

Gdzie znajduje się pełna implementacja fallbacku?

Zobacz How to Build Robust LLM Model Fallback Strategies po szerszą architekturę oraz przewodnik CometAPI po fallbacku modeli po szczegóły implementacji.

Uczyń klasyfikator błędów strażnikiem

Automatyczny fallback jest użyteczny, gdy jest wąski i obserwowalny. Pozwól, by błędy uwierzytelniania, ścieżki i nieprawidłowych żądań kończyły się głośno. Ponawiaj limity szybkości i tymczasowe awarie serwera z backoffem, a następnie przechodź do zgodnej trasy dopiero po wyczerpaniu budżetu ponowień. Taka polityka czyni fallback narzędziem niezawodności, a nie sposobem ukrywania błędów konfiguracji.

Źródła

• Kody błędów i obsługa w CometAPI
• Strategia błędów i ponowień w CometAPI
• Limity szybkości i współbieżność w CometAPI
• Przewodnik po bazowym URL CometAPI
• Przewodnik CometAPI po fallbacku modeli
• Pełny samouczek o fallbacku modeli