zpracování chyb webového IQ Microsoft

Všechna rozhraní API v3 vrací standardizované chybové odpovědi, které vám pomůžou rychle diagnostikovat a řešit problémy. Tato část popisuje stavové kódy HTTP, strukturu odpovědí na chyby a běžné scénáře řešení potíží.

Note

Všechny hodnoty výčtu řetězců nerozlišují malá a velká písmena.

Stavové kódy HTTP

Kód stavu	Platí pro	Kategorie chyb	Description	Běžné příčiny
200	Všechna rozhraní API	Success	Žádost byla úspěšná.	-
202	Procházet pouze	Akceptováno	Žádost byla přijata ke zpracování (živé procházení).	Probíhající procházení na vyžádání
400	Všechna rozhraní API	Nesprávná žádost	Neplatné parametry požadavku.	Chybí požadovaná pole, neplatné hodnoty parametrů, chybně formátovaný JSON.
401	Všechna rozhraní API	Neautorizováno	Ověřování se nezdařilo nebo chybí.	Neplatný klíč rozhraní API, chybějící hlavička x-apikey
403	Všechna rozhraní API	Zakázáno	Platné přihlašovací údaje, ale nedostatečná oprávnění	Klíč rozhraní API nemá požadovaná oprávnění
403	Procházet pouze	Zakázáno	Obsah filtrovaný nebo vyloučený z adresy URL	Adresa URL blokovaná zásadami nebo filtrovaným obsahem
404	Procházet pouze	Nenalezeno	Dokument nebyl nalezen.	Neplatná nebo nepřístupná adresa URL
410	Všechna rozhraní API	Pryč	Vyžaduje se HTTPS.	Požadavek provedený přes PROTOKOL HTTP místo HTTPS
415	Všechna rozhraní API	Nepodporovaný typ média	Typ obsahu není podporován.	Chybějící nebo nesprávná hlavička content-type
429	Všechna rozhraní API	Příliš mnoho požadavků	Byl překročen limit rychlosti.	Příliš mnoho požadavků v časovém intervalu
430	Procházet pouze	Chyba serveru	Příliš mnohoprocházeních	Nadměrné požadavky na živé procházení
500	Všechna rozhraní API	Vnitřní chyba serveru	Neočekávaná chyba serveru	Dočasný problém se serverem

Struktura odpovědi na chybu

Všechny odpovědi na chyby se řídí tímto schématem:

Field	Typ	Description
errorCode	řetězec	Podrobnější kategorie chyb, která pomáhá identifikovat typ chyby.
errorCategory	řetězec	Kategorie vysoké úrovně: UserError (na straně klienta / neopakovatelné) nebo SystemError (na straně serveru / opakovatelné).
userMessage	řetězec	Popis chyby čitelné člověkem
technicalDetails	řetězec (volitelné)	Další technické informace nebo podrobnosti o ověření parametrů pro ladění
retryAfter	řetězec (volitelné)	Doba čekání před opakováním
requestId	řetězec (volitelné)	Jedinečný identifikátor požadavku.
traceId	řetězec	ID distribuovaného trasování pro ladění a podporu Microsoft

Note

202 Accepted odpovědi (např. Procházet živé dotazování procházení) nejsou chybové odpovědi a nepoužívají výše uvedené schéma chyb. Stále můžou obsahovat retryAfter hodnotu, která bude indikovat, kdy se má požadavek opakovat.

Příklad odpovědi na chybu:

{
  "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"
}

Referenční informace ke kódům chyb

Chyby ověření požadavku

Kód chyby	Stav HTTP	Kategorie	Description
RequestInvalidFormat	400	UserError	Poškozený text JSON nebo neplatná struktura datové části požadavku
RequestInvalidMethod	400	UserError	Neplatná metoda nebo název nástroje zadaný v požadavku
HandlerInvalidInput	400	UserError	Neplatné hodnoty vstupních parametrů (například prázdný dotaz, maxResults mimo rozsah [1, 50], neplatné hodnoty výčtu).
RequestBlockedHeader	400	UserError	Požadavek obsahuje hlavičku ladění/varianty se seznamem blokovaných položek (napřX-Augmentations. , X-DebugOptions, ). X-XapHostOverride Místo toho použijte zdokumentované parametry adresy URL (?p1=, ?debugoptions=, ?atlahostname=).
RequestUnsupportedMediaType	415	UserError	Záhlaví content-type chybí nebo není application/json.
MethodNotAllowed	405	UserError	Metoda HTTP není na trase povolená (např. GET na koncovém bodu jen POST).

Chyby ověřování a autorizace

Kód chyby	Stav HTTP	Kategorie	Description
AuthNoToken	401	UserError	Vyžaduje se ověřování. Nebyl poskytnut nosný token ani klíč rozhraní API.
AuthTokenParse	401	UserError	Neplatný formát ověřovacího tokenu nebo analýza tokenu se nezdařila.
AuthInvalidApiKey	401	UserError	Zadaný klíč rozhraní API je neplatný nebo není rozpoznán.
AuthenticationFailed	401	UserError	Obecná chyba ověřování
AuthExpiredTrial	401	UserError	Zkušební období vypršelo. Upgradujte svůj klíč.
AuthMissingEntryId	400	UserError	Chybí identita aplikace nebo ID položky v kontextu požadavku.
AuthAppIdSelectionRequired	400	UserError	Vaše identita se mapuje na více aplikací. Zadejte cílovou aplikaci pomocí parametru APPID dotazu. Viz Volání více než jednoho APPID.
AuthUnauthorizedEntryId	401	UserError	Neautorizované ID položky. Identitu aplikace nebylo možné přeložit nebo APPID byl odeslán parametr dotazu s ověřováním klíče rozhraní API.
AuthUnauthorizedAppId	403	UserError	APPID Zadané není přidružené k vaší identitě.
AuthUnauthorizedService	403	UserError	Volající je ověřený, ale neautorizováno pro přístup k požadované službě nebo vertikálnímu přístupu.
AuthBatchEndpointRequired	403	UserError	Aplikace se vyžaduje k použití dávkového koncového bodu (X-FD-Batch: 1) pro vyhledávání na webu.
AuthMcpWebForbidden	403	UserError	Aplikace nemá povoleno používat nástroj MCP web .
AuthContentFormatForbidden	403	UserError	Tato aplikace má přístup pouze k pasážům. Použít contentFormatpassage. Viz pasáže a formáty obsahu.

Chyby omezování rychlosti

Kód chyby	Stav HTTP	Kategorie	Description
AuthUserThrottled	429	UserError	Frekvence požadavků překračuje limit rychlosti vašeho prostředku. Zaškrtněte políčko retryAfter.
AuthUserDailyUsageExceeded	429	UserError	Došlo k dosažení denní kvóty žádostí (resetuje se v 00:00 UTC). Zaškrtněte políčko retryAfter.

Chyby specifické pro procházení rozhraní API

Kód chyby	Stav HTTP	Kategorie	Description
BrowseApiDocNotFound	404	UserError	Dokument nebyl nalezen. Pro zadanou adresu URL není k dispozici žádný obsah.
BrowseApiIsFilteredOut	403	UserError	Výsledek se zahodil kvůli zásadám nebo filtrování obsahu.
BrowseApiIsUrlExcluded	403	UserError	Cílová adresa URL je vyloučena nebo zakázána zásadami.
BrowseApiTooManyOnDemandCrawls	430	UserError	Probíhá příliš mnoho žádostí živého procházení na vyžádání.

Chyby služby a infrastruktury

Kód chyby	Stav HTTP	Kategorie	Opakovatelné	Description
InternalServerError	500	SystemError	Ano (30s)	Vnitřní chyba serveru.

Běžné chybové scénáře

Chyby ověřování (401, 403)

Příznak: Ověřování selhalo nebo zakázáno

Řešení:

• Ověření správnosti klíče rozhraní API a jeho zahrnutí do hlavičky x-apikey
• Zkontrolujte, jestli nevypršela platnost klíče rozhraní API.
• Ujistěte se, že máte požadovaná oprávnění pro koncový bod.
• Pokud problémy potrvají, obraťte se na zástupce Microsoft.

Příklad:

# 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"}'

Omezování rychlosti (429)

Příznak: Překročení limitu rychlosti nebo vyčerpání denní kvóty (AuthUserThrottled nebo AuthUserDailyUsageExceeded)

Požadavky nad limit rychlosti vašeho prostředku vrací HTTP 429. Váš limit rychlosti se zobrazuje na webovém portálu IQ.

Řešení:

• Implementujte logiku opakování pokusů s exponenciálně rostoucí prodlevou
• Před opakováním počkejte na retryAfter interval v odpovědi na chybu (např "60s". )
• Snížení frekvence požadavků
• Všimněte si, že denní limit kvót (AuthUserDailyUsageExceeded) se každý den resetuje v 00:00 UTC.
• Pokud chcete požádat o vyšší limit, obraťte se na podporu webového IQ.

Příklad odpovědi:

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

Neplatné parametry (400)

Příznak: Chybný požadavek kvůli neplatným parametrům

Běžné problémy:

• Chybí požadovaná pole (např. query parametr)
• Hodnoty parametrů mimo rozsah (např maxResults> . 50)
• Neplatné typy parametrů (např. řetězec místo celého čísla)
• Nepodporované hodnoty parametrů (např. neplatné contentFormat)

Řešení:

• Ověřte, že jsou k dispozici všechny požadované parametry.
• Kontrola hodnot parametrů proti zdokumentovaným omezením
• Zajištění správného formátování JSON

Chyby serveru a infrastruktury (500)

Příznak: Neočekávaná vnitřní chyba serveru nebo upstreamové služby (InternalServerError)

Řešení:

• retryAfter Zkontrolujte pole (výchozí nastavení"30s") a po čekání zkuste požadavek zopakovat.
• Implementujte opakování pokusů s exponenciálním prodlužováním prodlevy a náhodnou odchylkou
• Pokud problém přetrvává, obraťte se na podporu Microsoft s traceId využitím poskytnuté odpovědi.

Příklad odpovědi:

{
  "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"
}

Odpověď přijatá rozhraní API pro procházení (202)

Příznak: Akceptovaná odpověď s polem retryAfter

Vysvětlení: Pokud liveCrawl je nastavená na "záložní" a adresa URL je potřeba procházet, rozhraní API vrátí hodnotu 202 Přijato s retryAfter hodnotou označující, kdy se má požadavek opakovat.

Zpracování:

# 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

Doporučené postupy

1. Vždy kontrolovat stavové kódy – Nepředpokládejte úspěch.
2. Použití traceId pro podporu – Zahrnutí traceId při kontaktování podpory
3. Implementace logiky opakování – Použití exponenciálního zpochybnění pro přechodné chyby
4. Zpracování odpovědí 202 – pro rozhraní API pro procházení s živým procházením, čekáním a opakováním
5. Ověření před odesláním – Zkontrolujte parametry místně, abyste se vyhnuli chybám 400.
6. Použít jenom HTTPS – Požadavky HTTP vrátí chyby 410