Obsługa błędów pozyskiwania zerobus

Na tej stronie opisano kody błędów zwracane przez interfejs API pozyskiwania zerobus oraz sposób obsługi ich przez klientów. Użyj tej dokumentacji podczas diagnozowania żądań, które zakończyły się niepowodzeniem lub implementowania logiki obsługi błędów w integracji.

Format odpowiedzi na błędy

Odpowiedzi na błędy obejmują kod błędu z możliwością odczytu maszyny i czytelny dla człowieka komunikat dostarczany w formacie odpowiednim dla twojego protokołu.

REST (JSON)

Odpowiedzi na błędy są zwracane jako kod JSON z odpowiednim kodem stanu HTTP:

{
  "error_code": "NOT_FOUND",
  "message": "Table \"catalog.schema.table\" cannot be found."
}
Pole danych Typ Opis
kod błędu ciąg Kod błędu z możliwością odczytu maszyny identyfikujący kategorię awarii. Służy do określania sposobu programowego obsługi błędu.
komunikat ciąg Czytelny dla człowieka opis błędu. Może zawierać dodatkowe informacje diagnostyczne na potrzeby rozwiązywania problemów. Nie analizuj tego pola programowo, ponieważ jego format może się zmienić bez powiadomienia.

gRPC

Odpowiedzi na błędy używają standardowych kodów stanu gRPC dostarczanych za pośrednictwem przyczep odpowiedzi:

Zwiastun Opis
grpc-status Kod stanu liczbowego (np. 3 dla elementu INVALID_ARGUMENT). Służy do określania sposobu programowego obsługi błędu.
grpc-message Czytelny dla człowieka opis błędu. Może zawierać dodatkowe informacje diagnostyczne na potrzeby rozwiązywania problemów. Nie analizuj tego pola programowo, ponieważ jego format może się zmienić bez powiadomienia.

Kody błędów

W poniższych sekcjach opisano kody błędów zwracane przez interfejs API pozyskiwania zerobus, odpowiednie kody na poziomie protokołu i zalecane zachowanie klienta.

Błędy klienta

Te błędy wskazują na problem z żądaniem. Nie należy ponawiać próby bez modyfikowania żądania.

Kod błędu (REST) Kod gRPC Stan HTTP Opis Zalecana akcja
INVALID_PARAMETER_VALUE INVALID_ARGUMENT(3) 400 Żądanie zawiera nieprawidłowe lub źle sformułowane dane wejściowe, takie jak brakujące pole wymagane, nieprawidłowy schemat lub nieobsługiwany format rekordu. Napraw żądanie i prześlij ponownie. Sprawdź pole, message aby uzyskać szczegółowe informacje o tym, który parametr jest nieprawidłowy.
NOT_FOUND NOT_FOUND(5) 404 Żądany zasób nie istnieje. Nie można na przykład odnaleźć określonej tabeli. Sprawdź, czy nazwa zasobu jest poprawna i czy istnieje.
NOT_IMPLEMENTED UNIMPLEMENTED(12) 501 Żądana operacja nie jest obsługiwana. Na przykład tabela używa nieobsługiwanej funkcji lub formatu danych. Nie ponawiaj próby. Sprawdź pole, message aby uzyskać szczegółowe informacje na temat tego, co nie jest obsługiwane.

Błędy uwierzytelniania i autoryzacji

Te błędy wskazują problemy z tożsamością lub uprawnieniami wywołującego. Nie należy ponawiać próby przy użyciu tych samych poświadczeń.

Kod błędu (REST) Kod gRPC Stan HTTP Opis Zalecana akcja
UNAUTHENTICATED UNAUTHENTICATED(16) 401 Żądanie nie ma prawidłowych poświadczeń uwierzytelniania. Może brakować tokenu, być może jest on pusty, wygasł lub nieprawidłowy. Odśwież lub podaj prawidłowy token uwierzytelniania i spróbuj ponownie.
PERMISSION_DENIED PERMISSION_DENIED(7) 403 Dzwoniący nie ma wystarczających uprawnień do wykonania żądanej operacji na określonym zasobie. Sprawdź, czy obiekt wywołujący ma wymagane uprawnienia (np. MODIFY, SELECT, USE_CATALOG, USE_SCHEMA) w zasobie docelowym.

Błędy serwera

Te błędy wskazują na problem po stronie serwera. Ponów próbę z wykładniczym wycofywaniem i zakłóceniami.

Kod błędu (REST) Kod gRPC Stan HTTP Opis Zalecana akcja
UNAVAILABLE UNAVAILABLE(14) 503 Usługa tymczasowo nie może obsłużyć żądania. Jest to zazwyczaj warunek przejściowy. Ponów próbę z wykładniczym wycofywaniem i zakłóceniami.
RESOURCE_EXHAUSTED RESOURCE_EXHAUSTED(8) 429 Usługa odrzuca żądania z powodu limitów zasobów. Jeśli to możliwe, zmniejsz współbieżność żądań. Ponów próbę z wykładniczym wycofywaniem i zakłóceniami.
INTERNAL_ERROR INTERNAL(13) 500 Wystąpił nieoczekiwany błąd wewnętrzny. Nie ponawiaj próby. Skontaktuj się z pomocą techniczną i podaj pełną odpowiedź na błąd w celu przeprowadzenia diagnostyki.
  • Last updated on