Udostępnij za pośrednictwem

Kody błędów interfejsu API usługi żądania

  • Artykuł

Identyfikator zweryfikowany przez firmę Microsoft zawiera interfejs API REST usługi żądań, który umożliwia wystawianie i weryfikowanie poświadczeń. W tym artykule określono kody błędów dla interfejsu API usługi żądania.

Błąd obiektu

W publicznej wersji zapoznawczej interfejs API usługi żądań zwrócił błędy w następującym formacie.

{
  "requestId": "4bb6726f77af7623ab52962323016442",
  "date": "Thu, 28 Apr 2022 14:30:54 GMT",
  "mscv": "17ppwf3uxR10MfRR.1",
  "error": {
    "code": "client_request.invalid_include_qr_code",
    "message": "The request contains `includeQRCode`, but it is not boolean."
  }
}

Ten format został teraz zmieniony na następujący, aby umożliwić zarówno prostszą obsługę błędów, jak i lepszą obsługę rozwiązywania problemów. W nowym formacie zewnętrzne pola błędu kodu i komunikatu mają ustandaryzowane wartości, podczas gdy obiekt innererror zawiera szczegółowe informacje na temat przyczyn błędu.

{
  "requestId": "782628eb-503a-4978-84f2-d7c634f25b15",
  "date": "Fri, 29 Apr 2022 11:20:19 GMT",
  "mscv": "QbBLwF7XAp0dt4Lw.1",
  "error": {
    "code": "badRequest",
    "message": "The request is invalid.",
    "innererror": {
      "code": "badOrMissingField",
      "message": "The request contains `includeQRCode`, but it is not boolean.",
      "target": "includeQRCode"
    }
  }
}
Własność Typ Opis
requestId struna Automatycznie wygenerowany identyfikator żądania.
date data Czas błędu.
mscv struna Wewnętrzny kod firmy Microsoft.
error błędów Obiekt błędu zewnętrznego

Typ błędu

Obiekt error jest teraz zgodny z kodem stanu HTTP zwróconym z wywołania interfejsu API w celu ułatwienia obsługi błędów dla deweloperów.

Własność Typ Opis
code struna Kod błędu zwracanego zgodny z kodem stanu HTTP.
message struna Ustandaryzowany komunikat o błędzie, który jest również zależny od zwróconego kodu stanu HTTP.
innererror Innererror Podaj szczegółowe informacje o przyczynie błędu.

Kody błędów i komunikaty

Poniżej przedstawiono możliwe wartości najwyższego poziomu code mapowane na różne zwrócone kody stanu HTTP.

Kod stanu HTTP kod Komunikat
400 badRequest Żądanie jest nieprawidłowe.
401 Nieautoryzowanych Żądany zasób wymaga uwierzytelnienia
403 zakazany Brak uprawnień do spełnienia tego żądania.
404 notFound Żądany zasób nie istnieje.
405 methodNotAllowed Żądana metoda nie jest dozwolona w żądanym zasobie.
406 notAcceptable Żądany format odpowiedzi nie jest obsługiwany.
408 requestTimeout Upłynął limit czasu żądania.
409 konflikt Serwer nie może spełnić żądania z powodu konfliktu serwera.
410 Poszedł Żądany zasób nie jest już dostępny.
411 contentLengthRequired Brak nagłówka Content-Length.
412 warunek wstępny Warunek wstępny dla tego żądania nie powiódł się.
413 payloadTooLarge Ładunek jest za duży.
414 uriTooLong Identyfikator URI jest za długi.
415 nieobsługiwany typMediaType Określony typ nośnika jest nieobsługiwany.
416 rangeNotSatisable Żądany zakres żądanych danych nie może być spełniony.
417 expectationFailed Nie można spełnić oczekiwanego nagłówka.
421 misdirectedRequest Nie można utworzyć odpowiedzi dla tego żądania.
422 unprocessableEntity Żądanie zawiera błędy semantyczne.
423 zablokowany Zasób źródłowy lub docelowy jest zablokowany.
429 tooManyRequests Zbyt wiele żądań, spróbuj ponownie później.
431 requestHeaderFieldsTooLarge Pole nagłówka żądania jest zbyt duże.
500 internalServerError Na serwerze wystąpił błąd ogólny.
501 notImplemented Serwer nie obsługuje żądanej funkcji.
502 badGateway zła odpowiedź odebrana z innej bramy.
503 serviceUnavailable Serwer jest tymczasowo niedostępny. Spróbuj ponownie później.
504 gatewayTimeout Przekroczono limit czasu odebrany z innej bramy.
507 insufficientStorage Nie można zapisać danych dla żądania.

Typ błędu wewnętrznego

Wewnętrzny obiekt błędu zawiera szczegółowe informacje o błędzie przydatne dla dewelopera w celu zbadania bieżącego błędu.

{
  "requestId": "782628eb-503a-4978-84f2-d7c634f25b15",
  "date": "Fri, 29 Apr 2022 11:20:19 GMT",
  "mscv": "QbBLwF7XAp0dt4Lw.1",
  "error": {
    "code": "badRequest",
    "message": "The request is invalid.",
    "innererror": {
      "code": "badOrMissingField",
      "message": "The request contains `includeQRCode`, but it is not boolean.",
      "target": "includeQRCode"
    }
  }
}
Własność Typ Opis
code struna Kod błędu wewnętrznego. Zawiera ustandaryzowany kod na podstawie typu błędu
message struna Wewnętrzny komunikat o błędzie. Zawiera szczegółowy komunikat o błędzie. W tym przykładzie pole includeQRCode jest nieprawidłowym typem.
target struna Fakultatywny. Element docelowy zawiera pole w żądaniu, które powoduje ten błąd. To pole jest opcjonalne i może nie być obecne, w zależności od typu błędu.

Kody błędów wewnętrznych

Kod Opis
badOrMissingField zwracane, gdy wystąpią problemy z walidacją żądania. Pole target zawiera pole w żądaniu, które powoduje problem.
notFound zwracany, gdy zasób, którego żąda klient, nie zostanie znaleziony. Pole target zawiera nazwę/identyfikator zasobu, który nie został znaleziony.
tokenError zwracane w przypadku wszelkich problemów z walidacją w tokenach, takich jak token internetowy JSON (JWT) i podobne. Pole target zawiera nazwę tokenu powodującą problem, jeśli ma to zastosowanie.
transientError zwrócone dla wszystkich przypadków, w których klient może uzyskać pomyślną odpowiedź, jeśli ponowi próbę żądania na późniejszym etapie. Typowym przykładem zwracania tego kodu jest zwrócenie kodu HTTP 429

Następne kroki