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, gdy liveCrawl jest "powrót"
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. W przypadku przeglądania ze szczegółowymi kodami błędów zwracane są również żądania zbyt wielu przeszukiwań na żądanie.	Zbyt wiele żądań w przedziale czasu lub nadmierne żądania przeszukiwania na żywo
430	Przeglądaj tylko	Błąd serwera	Zbyt wiele przeszukiwań na żądanie (starsze kody błędów).	Nadmierne żądania przeszukiwania na żywo
500	Wszystkie interfejsy API	Wewnętrzny błąd serwera	Nieoczekiwany błąd serwera.	Tymczasowy problem z serwerem
520	Przeglądaj tylko	Przetwarzanie zawartości nie powiodło się	Strona została pobrana, ale nie można utworzyć zawartości użytecznej.	Przetwarzanie dokumentów nie powiodło się lub upłynął limit czasu lub upłynął limit czasu renderowania dynamicznego
523	Przeglądaj tylko	Przeszukiwanie anulowane	Adres URL nie wygenerował żadnej zawartości, ponieważ przeszukiwanie nie powiodło się z powodu ograniczonego limitu przydziału przeszukiwania witryny.	Ograniczony limit przydziału przeszukiwania dla hosta źródłowego
524	Przeglądaj tylko	Limit czasu przeszukiwania	Adres URL nie wygenerował żadnej zawartości, ponieważ upłynął limit czasu przeszukiwania.	Przekroczono limit czasu hosta zdalnego

Stany 520, 523 i 524 są częścią szczegółowych kodów błędów przeglądania, które są domyślnie włączone.

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)	Wskazówki dotyczące ponawiania prób. W przypadku AuthUserThrottledwartości , AuthUserDailyUsageExceededi InternalServerErrorczas trwania z sufiksem "s" (na przykład "60s"). W przypadku przeglądania szczegółowych błędów, w tym TooManyOnDemandCrawls (429), znacznik czasu ISO 8601 UTC (na przykład "2026-10-30T01:01:00Z"), który jest najwcześniejszym czasem ponawiania próby. Pominięto, gdy nie ma zastosowania żadne wskazówki dotyczące ponawiania prób.
requestId	ciąg (opcjonalnie)	Unikatowy identyfikator żądania.
traceId	ciąg	Identyfikator śledzenia rozproszonego na potrzeby debugowania i obsługi Microsoft.

Note

retryAfter używa dwóch formatów. AuthUserThrottled, AuthUserDailyUsageExceededi InternalServerError odpowiedzi używają czasu trwania, takiego jak "60s". Przeglądaj odpowiedzi i Przeglądaj 202 Accepted szczegółowe błędy używają bezwzględnego znacznika czasu ISO 8601 UTC, takiego jak "2026-10-30T01:01:00Z". Sam stan HTTP nie określa formatu: zwraca wartość 429, TooManyOnDemandCrawls ale używa znacznika czasu. Logika ponawiania prób powinna obsługiwać oba formaty.

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. Zawierają one sygnaturę czasową wskazującą retryAfter , kiedy ponowić żądanie.

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). W przypadku żądań query przeglądania fragmentów brakuje, pustych lub dłuższych niż 1000 znaków.
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 identyfikatora AppID. 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

Szczegółowe kody błędów są domyślnie włączone dla opcji Przeglądaj. Identyfikują one konkretny powód, dla którego nie można zwrócić strony, na przykład filtrowanie zawartości, brakujący dokument lub błąd przeszukiwania, i zawierają wskazówki dotyczące ponawiania, jeśli ma to zastosowanie. Nie jest wymagane żadne wyrażenie zgody ani żądanie pomocy technicznej.

Szczegółowe i starsze kody używają standardowej struktury odpowiedzi na błędy. Przejrzyj błędy, które nie są wymienione tutaj, są zgłaszane jako InternalServerError (HTTP 500).

Starsze kody błędów przeglądania

Te kody były używane przed szczegółowymi kodami błędów stały się domyślne. Są one wymienione w celu uzyskania informacji podczas obsługi starszych odpowiedzi.

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 przez zasady zawartości, filtrowanie dla dorosłych, ograniczenia dostępu lub ograniczenia domeny.
BrowseApiIsUrlExcluded	403	UserError	Docelowy adres URL jest wykluczony przez zasady wykluczania robots.txt lub przeszukiwania.
BrowseApiTooManyOnDemandCrawls	430	UserError	Zbyt wiele żądań przeszukiwania na żądanie w toku. Zmniejsz szybkość przeszukiwania na żywo.

Szczegółowe kody błędów przeglądania

Kod błędu	Status HTTP	Category	Typowe retryAfter	userMessage	Zalecana akcja
InvalidUrl	400	UserError	Pominięty	Żądany adres URL jest nieprawidłowy.	Popraw adres URL przed ponowną próbą.
NotSupported	400	UserError	Pominięty	Żądany adres URL nie jest obsługiwany.	Użyj adresu URL wskazującego obsługiwany dokument internetowy.
URLFilteredOutSpamAdult	403	UserError	Około 24 godzin	Żądany adres URL został przefiltrowany przez zasady spamu lub osoby dorosłej.	Nie można zwrócić strony. Nie ponawiaj próby przed .retryAfter
URLFilteredOutEncumbrance	403	UserError	Około 24 godzin	Żądany adres URL został przefiltrowany według ograniczeń zawartości.	Zasady wydawcy lub witryny, takie jak dyrektywy robotów lub reguły paywall, nie zezwalają na zwracanie zawartości. Nie ponawiaj próby przed .retryAfter
URLFilteredOutSource403Forbidden	403	UserError	Około 24 godzin	Źródło odmówiło dostępu do żądanego adresu URL.	Lokacja źródłowa zwróciła protokół HTTP 403. Nie ponawiaj próby przed .retryAfter
BrowseApiIsFilteredOut	403	UserError	Około 24 godzin po podaniu	Żądany adres URL został odfiltrowany.	Zwracany, gdy strona jest filtrowana z powodu, że nie obejmuje bardziej szczegółowego kodu. Nie ponawiaj próby przed .retryAfter
DocNotFound	404	UserError	Pominięto, chyba że usługa przeszukiwania jest dostarczana	Nie można odnaleźć żądanego dokumentu.	Sprawdź adres URL lub ustaw liveCrawl wartość "fallback", aby zażądać przeszukiwania na żywo.
TooManyOnDemandCrawls	429	UserError	W przypadku dostarczenia przez usługę przeszukiwania	Zażądano zbyt wielu przeszukiwań na żądanie.	Zmniejsz szybkość przeszukiwania na żywo. Jeśli retryAfter jest obecny, zaczekaj na ten czas przed ponowną próbą.
FailedNoContent	520	SystemError	Około 5 minut	Przetwarzanie lub publikowanie dokumentów nie może wygenerować zawartości użytecznej.	Ponów próbę po .retryAfter
DynamicRenderingTimeout	520	SystemError	Około 5 minut	Upłynął limit czasu renderowania strony dynamicznej.	Ponów próbę po , retryAfterlub ponów próbę bez renderDynamicPages.
ProcessingTimeout	520	SystemError	Około 5 minut	Upłynął limit czasu przetwarzania dokumentów.	Ponów próbę po .retryAfter
PolitenessCancellation	523	SystemError	Około 5 minut	Przeszukiwanie zostało anulowane w celu przestrzegania limitów przeszukiwania hosta źródłowego.	Adres URL nie wygenerował żadnej zawartości, ponieważ przeszukiwanie nie powiodło się z powodu ograniczonego limitu przydziału przeszukiwania witryny. Ponów próbę po .retryAfter
HostCrawlTimeout	524	SystemError	Około 5 minut	Upłynął limit czasu przeszukiwania hosta źródłowego.	Adres URL nie wygenerował żadnej zawartości, ponieważ przekroczono limit czasu przeszukiwania: host zdalny nie odpowiedział na czas. Ponów próbę po .retryAfter

Gdy ma zastosowanie opóźnienie ponawiania, odpowiedź będzie zawierać retryAfter jako znacznik czasu ISO 8601 UTC w formacie yyyy-MM-ddTHH:mm:ssZ, na przykład "retryAfter": "2026-10-30T01:01:00Z". Nie próbuj ponownie przed tym czasem. Po retryAfter pominięciu nie ma zastosowania żadne wskazówki dotyczące ponawiania prób.

Przykładowa szczegółowa odpowiedź na błąd:

{
  "errorCode": "URLFilteredOutEncumbrance",
  "errorCategory": "UserError",
  "userMessage": "The requested URL was filtered by content restrictions.",
  "retryAfter": "2026-10-31T01:00:00Z",
  "traceId": "0123456789abcdef0123456789abcdef"
}

Przeglądanie błędów fragmentów

Te błędy dotyczą żądań przeglądania z elementami contentFormat: "passage", w tym żądań z aplikacji bez pełnego dostępu do dokumentów, dla których "fragment" jest formatem domyślnym. Zobacz Przeglądanie żądań fragmentów.

Warunek	Kod błędu	Status HTTP	userMessage
query brakujące, puste, tylko odstępy lub więcej niż 1000 znaków	HandlerInvalidInput	400	Podano nieprawidłowe dane wejściowe. Sprawdź parametry żądania.
Aplikacja bez pełnych żądań textdostępu do dokumentów , htmllub markdown	AuthContentFormatForbidden	403	Ta aplikacja ma dostęp tylko do fragmentów. Użyj elementu contentFormat "passage".

Wszystkie inne wyniki przeglądania dla żądań fragmentów używają tych samych kodów stanu i kodów błędów co text, htmli markdown żądania. Obejmuje to przefiltrowane strony, nie odnalezione dokumenty, oczekujące przeszukiwanie na żywo (202 Accepted) i błędy przeszukiwania.

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 identyfikatora AppID 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ź (202) z polami url i retryAfter w treści odpowiedzi

Wyjaśnienie: Gdy liveCrawl element jest "rezerwowy", a adres URL nie znajduje się w indeksie, interfejs API może rozpocząć przeszukiwanie asynchronicznie i zwrócić wartość 202 Zaakceptowane. Przeszukiwanie na żywo podlega ograniczeniom uprzejmości wydawcy i dostępności; "powrót" nie gwarantuje rzeczywistego przeszukiwania. To samo zachowanie ma zastosowanie do każdego contentFormatelementu , w tym passage.

Obsługa:

1. Sprawdź stan HTTP 202.
2. Odczyt retryAfter z treści odpowiedzi. Jest to sygnatura czasowa ISO 8601 UTC (na przykład "2026-10-30T01:01:00Z"), która jest najwcześniejszym czasem ponawiania próby.
3. Poczekaj do tego czasu.
4. Ponownie wyślij to samo żądanie. Pole zawiera adres URL do żądania. Domyślnie url jest to żądany adres URL.
5. Ogranicz liczbę prób sondowania. Przeszukiwanie, które nie może zakończyć się ostatecznie, zwraca błąd, taki jak HostCrawlTimeout (524) lub FailedNoContent (520).

# 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", "contentFormat": "passage", "query": "information about this domain", "liveCrawl": "fallback"}'

# Example response when the URL isn't indexed: 202 Accepted with "retryAfter": "2026-10-30T01:01:00Z"
# Wait until that time, then send the same request again

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 na czas i ponów próbę retryAfter
5. Obsługa obu retryAfter formatów — użyj czasu trwania dla AuthUserThrottledAuthUserDailyUsageExceeded, i InternalServerErrori znacznika czasu ISO 8601 dla przeglądania 202 i szczegółowych błędów, w tym TooManyOnDemandCrawls (429)
6. Sprawdź poprawność przed wysłaniem — sprawdź parametry lokalnie, aby uniknąć błędów 400
7. Użyj tylko protokołu HTTPS — żądania HTTP będą zwracać błędy 410