Microsoft obsługa błędów internetowego IQ

Wszystkie interfejsy API w wersji 3 zwracają ustandaryzowane odpowiedzi o błędach, aby ułatwić szybkie diagnozowanie i rozwiązywanie problemów. W tej sekcji opisano kody stanu HTTP, strukturę odpowiedzi na błędy i typowe scenariusze rozwiązywania problemów.

Note

Wszystkie wartości wyliczenia ciągów są bez uwzględniania wielkości liter.

kody stanu HTTP

Kod stanu	Ma zastosowanie do	Kategoria błędów	Description	Typowe przyczyny
200	Wszystkie interfejsy API	Powodzenie	Żądanie zakończyło się pomyślnie.	-
202	Przeglądaj tylko	Zaakceptowano	Żądanie zaakceptowane do przetwarzania (przeszukiwanie na żywo).	Przeszukiwanie na żądanie jest w toku
400	Wszystkie interfejsy API	Nieprawidłowe żądanie	Nieprawidłowe parametry żądania.	Brak wymaganych pól, nieprawidłowe wartości parametrów, nieprawidłowo sformułowany kod JSON
401	Wszystkie interfejsy API	Brak autoryzacji	Uwierzytelnianie nie powiodło się lub nie powiodło się.	Nieprawidłowy klucz interfejsu API, brak nagłówka x-apikey
403	Wszystkie interfejsy API	Dostęp zabroniony	Prawidłowe poświadczenia, ale niewystarczające uprawnienia.	Klucz interfejsu API nie ma wymaganych uprawnień
403	Przeglądaj tylko	Dostęp zabroniony	Zawartość filtrowana lub wykluczona z adresu URL.	Adres URL zablokowany przez zasady lub filtrowaną zawartość
404	Przeglądaj tylko	Nie znaleziono	Nie można odnaleźć dokumentu.	Nieprawidłowy lub niedostępny adres URL
410	Wszystkie interfejsy API	Zniknęło	Wymagany protokół HTTPS.	Żądanie wykonane za pośrednictwem protokołu HTTP zamiast HTTPS
415	Wszystkie interfejsy API	Nieobsługiwany typ nośnika	Typ zawartości nie jest obsługiwany.	Brak lub niepoprawny content-type nagłówek
429	Wszystkie interfejsy API	Zbyt wiele żądań	Przekroczono limit szybkości.	Zbyt wiele żądań w przedziale czasu
430	Przeglądaj tylko	Błąd serwera	Zbyt wiele przeszukiwań na żądanie.	Nadmierne żądania przeszukiwania na żywo
500	Wszystkie interfejsy API	Wewnętrzny błąd serwera	Nieoczekiwany błąd serwera.	Tymczasowy problem z serwerem

Struktura odpowiedzi na błędy

Wszystkie odpowiedzi na błędy są zgodne z tym schematem:

Pole	Typ	Description
errorCode	ciąg	Bardziej szczegółowa kategoria błędów, która pomaga zidentyfikować typ błędu.
errorCategory	ciąg	Kategoria wysokiego poziomu: UserError (po stronie klienta / nie można ponowić próby) lub SystemError (po stronie serwera / ponawianie próby).
userMessage	ciąg	Opis błędu czytelnego dla człowieka.
technicalDetails	ciąg (opcjonalnie)	Dodatkowe informacje techniczne lub szczegóły weryfikacji parametrów na potrzeby debugowania.
retryAfter	ciąg (opcjonalnie)	Czas oczekiwania przed ponowną próbą.
requestId	ciąg (opcjonalnie)	Unikatowy identyfikator żądania.
traceId	ciąg	Identyfikator śledzenia rozproszonego na potrzeby debugowania i obsługi Microsoft.

Note

202 Accepted odpowiedzi (np. Przeglądanie sondowania przeszukiwania na żywo) nie są odpowiedziami na błędy i nie używają powyższego schematu błędów. Mogą one nadal zawierać wartość wskazującą retryAfter , kiedy ponowić próbę żądania.

Przykładowa odpowiedź na błąd:

{
  "errorCode": "HandlerInvalidInput",
  "errorCategory": "UserError",
  "userMessage": "Invalid input provided. Please check your request parameters.",
  "technicalDetails": "Parameter validation failed: maxResults=100 exceeds maximum=50",
  "requestId": "req_abc123",
  "traceId": "trace_xyz789"
}

Odwołanie do kodów błędów

Błędy weryfikacji żądań

Kod błędu	Status HTTP	Category	Description
RequestInvalidFormat	400	UserError	Źle sformułowana treść JSON lub nieprawidłowa struktura ładunku żądania.
RequestInvalidMethod	400	UserError	Nieprawidłowa nazwa metody lub narzędzia określona w żądaniu.
HandlerInvalidInput	400	UserError	Nieprawidłowe wartości parametrów wejściowych (np. puste zapytanie, maxResults poza zakresem [1, 50], nieprawidłowe wartości wyliczenia).
RequestBlockedHeader	400	UserError	Żądanie zawiera nagłówek debugowania/wariantu bloku (np. X-Augmentations, X-DebugOptions, X-XapHostOverride). Zamiast tego użyj udokumentowanych parametrów adresu URL (?p1=, ?debugoptions=, ?atlahostname=).
RequestUnsupportedMediaType	415	UserError	Brak nagłówka content-type lub nie application/json.
MethodNotAllowed	405	UserError	Metoda HTTP nie jest dozwolona na trasie (np. GET w punkcie końcowym TYLKO POST).

Błędy uwierzytelniania i autoryzacji

Kod błędu	Status HTTP	Category	Description
AuthNoToken	401	UserError	Wymagane jest uwierzytelnianie. Nie podano tokenu elementu nośnego ani klucza interfejsu API.
AuthTokenParse	401	UserError	Nieprawidłowy format tokenu uwierzytelniania lub analizowanie tokenu nie powiodło się.
AuthInvalidApiKey	401	UserError	Podany klucz interfejsu API jest nieprawidłowy lub nie został rozpoznany.
AuthenticationFailed	401	UserError	Błąd uwierzytelniania ogólnego.
AuthExpiredTrial	401	UserError	Okres próbny wygasł. Uaktualnij klucz.
AuthMissingEntryId	400	UserError	Brak tożsamości aplikacji/identyfikatora wpisu w kontekście żądania.
AuthAppIdSelectionRequired	400	UserError	Tożsamość jest mapowana na wiele aplikacji. Określ aplikację docelową przy użyciu parametru APPID zapytania. Zobacz Wywoływanie więcej niż jednego identyfikatora AppID.
AuthUnauthorizedEntryId	401	UserError	Nieautoryzowany identyfikator wpisu. Nie można rozpoznać tożsamości aplikacji lub parametr zapytania został wysłany przy użyciu uwierzytelniania klucza interfejsu APPID API.
AuthUnauthorizedAppId	403	UserError	Określona APPID wartość nie jest skojarzona z twoją tożsamością.
AuthUnauthorizedService	403	UserError	Obiekt wywołujący jest uwierzytelniany, ale nieautoryzowany w celu uzyskania dostępu do żądanej usługi/pionowej.
AuthBatchEndpointRequired	403	UserError	Aplikacja jest wymagana do korzystania z punktu końcowego wsadowego (X-FD-Batch: 1) na potrzeby wyszukiwania w Internecie.
AuthMcpWebForbidden	403	UserError	Aplikacja nie może używać narzędzia MCP web .
AuthContentFormatForbidden	403	UserError	Ta aplikacja ma dostęp tylko do fragmentów. Użyj polecenia contentFormatpassage. Zobacz Fragmenty i formaty zawartości.

Błędy ograniczania szybkości

Kod błędu	Status HTTP	Category	Description
AuthUserThrottled	429	UserError	Częstotliwość żądań przekracza limit szybkości zasobu. Sprawdź retryAfter.
AuthUserDailyUsageExceeded	429	UserError	Osiągnięto dzienny limit przydziału żądań (resetowanie o godzinie 00:00 UTC). Sprawdź retryAfter.

Przeglądanie błędów specyficznych dla interfejsu API

Kod błędu	Status HTTP	Category	Description
BrowseApiDocNotFound	404	UserError	Nie można odnaleźć dokumentu. Brak dostępnej zawartości dla określonego adresu URL.
BrowseApiIsFilteredOut	403	UserError	Wynik został porzucony z powodu filtrowania zasad lub zawartości.
BrowseApiIsUrlExcluded	403	UserError	Docelowy adres URL jest wykluczony lub niedozwolony przez zasady.
BrowseApiTooManyOnDemandCrawls	430	UserError	Zbyt wiele żądań przeszukiwania na żądanie w toku.

Błędy usługi i infrastruktury

Kod błędu	Status HTTP	Category	Wznawialny	Description
InternalServerError	500	SystemError	Tak (30s)	Wewnętrzny błąd serwera.

Typowe scenariusze błędów

Błędy uwierzytelniania (401, 403)

Objaw: Uwierzytelnianie nie powiodło się lub dostęp zabroniony

Rozwiązania:

• Sprawdź, czy klucz interfejsu API jest poprawny i uwzględniony w nagłówku x-apikey
• Sprawdź, czy klucz interfejsu API nie wygasł
• Upewnij się, że masz wymagane uprawnienia dla punktu końcowego
• Skontaktuj się z przedstawicielem Microsoft, jeśli problemy będą się powtarzać

Example:

# Correct authentication
curl -X POST "https://api.microsoft.ai/v3/search/web" \
  -H "x-apikey: your-valid-key-here" \
  -H "content-type: application/json" \
  -d '{"query": "test"}'

Ograniczanie szybkości (429)

Objaw: Przekroczono limit szybkości lub wyczerpano dzienny limit przydziału (AuthUserThrottled lub AuthUserDailyUsageExceeded)

Żądania powyżej limitu szybkości zasobu zwracają http 429. Limit szybkości jest wyświetlany w portalu internetowego IQ.

Rozwiązania:

• Zaimplementować logikę ponawiania prób z wykładniczo rosnącym odstępem
• Przed ponowieniu próby poczekaj retryAfter interwał odpowiedzi na błąd (np. "60s")
• Zmniejsz częstotliwość żądań
• Należy pamiętać, że dzienne limity przydziału (AuthUserDailyUsageExceeded) są resetowane codziennie o godzinie 00:00 UTC
• Aby zażądać wyższego limitu, skontaktuj się z pomocą techniczną internetową IQ

Przykładowa odpowiedź:

{
  "errorCode": "AuthUserThrottled",
  "errorCategory": "UserError",
  "userMessage": "Rate limit exceeded. Please reduce your request frequency.",
  "retryAfter": "60s",
  "requestId": "req_123",
  "traceId": "trace_456"
}

Nieprawidłowe parametry (400)

Objaw: Nieprawidłowe żądanie z powodu nieprawidłowych parametrów

Typowe problemy:

• Brak wymaganych pól (np. query parametru)
• Wartości parametrów poza zakresem (np. maxResults> 50)
• Nieprawidłowe typy parametrów (np. ciąg zamiast liczby całkowitej)
• Nieobsługiwane wartości parametrów (np. nieprawidłowe contentFormat)

Rozwiązania:

• Sprawdź, czy wszystkie wymagane parametry są obecne
• Sprawdzanie wartości parametrów pod kątem udokumentowanych ograniczeń
• Zapewnianie prawidłowego formatowania JSON

Błędy serwera i infrastruktury (500)

Objaw: Nieoczekiwany wewnętrzny błąd serwera lub usługi nadrzędnej (InternalServerError)

Rozwiązania:

• Sprawdź pole (wartość domyślna to "30s") i ponów próbę żądania po oczekiwaniu retryAfter
• Zaimplementuj ponawianie z wykładniczo rosnącym opóźnieniem i losowym opóźnieniem
• Jeśli problem będzie się powtarzać, skontaktuj się z pomocą techniczną Microsoft z podanym traceId w odpowiedzi

Przykładowa odpowiedź:

{
  "errorCode": "InternalServerError",
  "errorCategory": "SystemError",
  "userMessage": "The service is temporarily unavailable. Please try again later.",
  "technicalDetails": "An internal service error occurred. Please contact support if the issue persists.",
  "retryAfter": "30s",
  "traceId": "trace_456"
}

Przeglądanie zaakceptowanej odpowiedzi interfejsu API (202)

Objaw: Zaakceptowana odpowiedź z retryAfter polem

Wyjaśnienie: Gdy liveCrawl parametr ma wartość "rezerwowy", a adres URL musi zostać przeszukany, interfejs API zwraca wartość 202 Accepted z wartością wskazującą, kiedy ponowić próbę retryAfter żądania.

Obsługa:

# Initial request
curl -X POST "https://api.microsoft.ai/v3/browse" \
  -H "x-apikey: your-key" \
  -H "content-type: application/json" \
  -d '{"url": "https://example.com", "liveCrawl": "fallback"}'

# Response: 202 Accepted with retryAfter
# Wait for the specified time, then retry the same request

Najlepsze praktyki

1. Zawsze sprawdzaj kody stanu — nie zakładaj powodzenia
2. Użyj traceId w celu uzyskania pomocy technicznej — dołącz identyfikator traceId podczas kontaktowania się z pomocą techniczną
3. Implementowanie logiki ponawiania prób — używanie wycofywania wykładniczego dla błędów przejściowych
4. Obsługa odpowiedzi 202 — w przypadku interfejsu API przeglądania przy użyciu przeszukiwania na żywo poczekaj i ponów próbę
5. Sprawdź poprawność przed wysłaniem — sprawdź parametry lokalnie, aby uniknąć błędów 400
6. Użyj tylko protokołu HTTPS — żądania HTTP będą zwracać błędy 410