Kody błędów i diagnozowanie

Ustal, co zawiodło

1. Zapisz rzeczywisty status HTTP, metodę i ścieżkę żądania. Status HTTP i kod błędu aplikacji opisują różne warstwy; nie zastępuj jednego drugim.
2. Odczytuj pola błędów zgodnie z wywołanym protokołem. Odpowiedzi natywne, OpenAI, Claude i Gemini nie mają wspólnej struktury we wszystkich przypadkach.
3. Dla żądań strumieniowych sprawdź także zdarzenia błędów i stan ukończenia. Dla zadań asynchronicznych sprawdź status zadania. HTTP 200 nie gwarantuje udanego generowania.
4. Użyj poniższej tabeli, aby poprawić żądanie lub zdecydować o ponowieniu. message jest tekstem objaśniającym, a nie stabilnym wyliczeniem; nie uzależniaj logiki od jego brzmienia.

Wyliczenie kodów błędów platformy

To kompletne wyliczenie kodów błędów aplikacyjnych platformy. Nazwy są etykietami referencyjnymi; wartości code w odpowiedzi są liczbami. „Typowy HTTP” jest wskazówką diagnostyczną, a nie stałym mapowaniem każdego punktu końcowego. Używaj rzeczywistego statusu HTTP i treści odpowiedzi. code przekazany od dostawcy może nie należeć do tego wyliczenia.

Sam HTTP 429 nie pozwala wiarygodnie odróżnić limitu częstotliwości od limitu współbieżności. Rozróżniaj je tylko przy dostępnym jawnym numerycznym kodzie błędu. Sprawdź identyfikatory modeli na liście modeli; nie przepisuj samodzielnie wartości model.

Odczytywanie błędów według protokołu

Poniższe przykłady pokazują typowe struktury generowane przez platformę, a nie jeden format gwarantowany dla każdego błędu. Błędy uwierzytelnienia mogą pochodzić z różnych warstw przetwarzania, a odpowiedzi przekazywane od dostawcy mogą zachować własne struktury, kody tekstowe lub typy. Przed parsowaniem rozpoznaj rzeczywistą strukturę odpowiedzi. Jeśli jest nieznana, zachowaj oryginalne pola i status HTTP zamiast wymuszać konwersję.

Natywne API platformy

Zwykle odczytuj error.code i error.message. requestId może nie występować.

{
  "success": false,
  "error": {
    "code": 10000,
    "message": "Bad request"
  },
  "requestId": "req_example"
}

Niektóre błędy mogą używać code i message najwyższego poziomu. Klienci powinni tolerować tę różnicę i nie mogą traktować braku obiektu error jako dowodu sukcesu. Odpowiedzi walidacji parametrów mogą też nie zawierać numerycznego kodu błędu. Traktuj brakujący kod jako nieznany zamiast go wymyślać.

API zgodne z OpenAI

Typowe błędy generowane przez platformę używają code, message i type najwyższego poziomu; nie muszą być opakowane w error.

{
  "code": 40000,
  "message": "Insufficient credit",
  "type": "api_error"
}

type jest kategorią protokołu; code w tej strukturze to numeryczny kod błędu platformy. Samo api_error nie określa zasadności ponowienia. Błędy przekazywane od dostawcy i błędy strumieniowe mogą zawierać zagnieżdżone error; obsługuj rzeczywistą odpowiedź protokołu. Zobacz Chat Completions i Responses.

API zgodne z Claude

W typowej strukturze type najwyższego poziomu to error, konkretna kategoria to error.type, a opis to error.message. Ta struktura nie zawiera numerycznego code platformy. Nie wymyślaj go.

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens must be a positive safe integer"
  }
}

Platforma lokalnie generuje poniższe typy błędów Claude. Nie jest to pełne wyliczenie typów błędów dostawcy.

Zobacz wiadomości Claude.

Błędy w stylu Gemini

Gdy otrzymasz odpowiedź w stylu Gemini, odczytaj error.code, error.message i error.status. Tutaj status jest kategorią tekstową, a nie statusem HTTP lub zadania asynchronicznego.

{
  "error": {
    "code": 10000,
    "message": "Bad request",
    "status": "INVALID_ARGUMENT"
  }
}

Błędy generowane przez platformę w tej strukturze używają numerycznych wartości code platformy. Poniżej znajduje się lokalne mapowanie tekstowego status; nie jest to wyliczenie wszystkich statusów dostawcy.

503 ma pierwszeństwo i używa UNAVAILABLE, a nie INTERNAL. Odpowiedzi dostawcy mogą mieć inną semantykę code i status. Nie stosuj tabeli błędów platformy do każdego numerycznego kodu Gemini.

Bezpieczne ponawianie

Respektuj poprawny nagłówek Retry-After, jeśli występuje. Nie zakładaj, że zawiera go każdy błąd. Automatyczne ponowienie nieidempotentnego żądania generowania może wykonać je ponownie i naliczyć dodatkowe opłaty. Ta strona nie obiecuje ogólnej obsługi kluczy idempotencji; samodzielne dodanie Idempotency-Key nie gwarantuje deduplikacji.

Jeśli masz już jobId, sprawdź to zadanie przed utworzeniem kolejnego. Jeśli nie masz jobId, a wynik jest niepewny, zachowaj identyfikator żądania i znacznik czasu do analizy.

Strumienie i zadania asynchroniczne

Żądania SSE

Po rozpoczęciu SSE status HTTP może pozostać 200, podczas gdy późniejszy błąd zostanie zgłoszony przez zdarzenie lub dane błędu w strumieniu. Parsuj zdarzenia i dane wybranego protokołu oraz sprawdzaj prawidłowe ukończenie. Przy błędzie lub nieoczekiwanym rozłączeniu nie traktuj częściowego tekstu lub obrazów jako pełnego udanego wyniku. Nazwy zdarzeń i ich dane różnią się między punktami końcowymi. Nie sprawdzaj tylko jednego stałego pola error ani nie używaj „otrzymano dowolny tekst” jako warunku sukcesu.

Zadania asynchroniczne

Odpowiedź utworzenia zawierająca data.jobId oznacza przyjęcie żądania, a nie ukończenie generowania. Udana odpowiedź HTTP przy odpytywaniu zadania oznacza powodzenie zapytania. Nadal musisz sprawdzić data.status zadania:

• PENDING, CONNECT, PROCESSING: kontynuuj odpytywanie zgodnie z dokumentacją Jobs.
• COMPLETED: odczytaj outputResult.
• FAILED, CANCELLED: zatrzymaj odpytywanie i zachowaj ID zadania oraz informacje odpowiedzi bez danych wrażliwych do analizy.

Szczegóły błędu mogą pojawić się w data.outputResult.error. Pole jest opcjonalne i nie jest gwarantowane dla każdego nieudanego zadania. Używaj Jobs tylko wtedy, gdy odpowiedź utworzenia jawnie zwraca jobId. Nie stosuj odpytywania zadań do punktów końcowych zwracających wyniki bezpośrednio przez JSON lub SSE.

Diagnostyka dla użytkowników i asystentów AI

Przekaż wsparciu lub asystentowi AI poniższe informacje po usunięciu danych wrażliwych. Dla brakujących pól użyj unknown; dla statusu HTTP użyj unknown, jeśli nie otrzymano odpowiedzi HTTP. Zachowaj ścieżki pól i oryginalne typy wartości, na przykład error.code: 10000 (number) lub error.code: "invalid_api_key" (string). Nie konwertuj automatycznie tekstowego code na numeryczny kod platformy ani nie wymyślaj brakujących pól z message, statusu HTTP lub nazw modeli.

time_with_timezone: unknown
method: unknown
path_without_query: unknown
model: unknown
stream: unknown
http_status: unknown
error_code_path_value_and_type: unknown
error_type_path_and_value: unknown
protocol_status_path_and_value: unknown
sanitized_message: unknown
request_id_from_body_or_X-Request-ID: unknown
job_id: unknown
job_status: unknown
retry_after: unknown
retry_count_and_delays: unknown
received_partial_output: unknown

Odczytaj requestId z treści odpowiedzi lub nagłówka odpowiedzi X-Request-ID, gdy są dostępne. Zachowaj jobId jako ciąg znaków, aby nie utracić precyzji długich liczb. Podaj tylko minimalne parametry żądania bez danych wrażliwych. Usuń klucze API, tokeny, pliki cookie, pełne nagłówki uwierzytelnienia, dane osobowe, prywatne prompty i treść plików wejściowych. Usuń parametry zapytań URL oraz adresy wejścia lub wyjścia zawierające podpisy lub dane dostępu. Nie wklejaj pełnych logów żądań bez ich przeglądu.

Asystenci AI powinni odróżniać zaobserwowane pola od możliwych przyczyn i wskazywać brakujące informacje. Niedostateczne dowody nie mogą być uznawane za potwierdzenie sukcesu żądania, braku wykonania lub braku opłaty.