Microsoft webes IQ-hibakezelés

Minden v3 API szabványos hibaválaszt ad vissza, hogy segítsen a problémák gyors diagnosztizálásában és megoldásában. Ez a szakasz a HTTP-állapotkódokat, a hibaválasz struktúráját és a gyakori hibaelhárítási forgatókönyveket ismerteti.

Note

Minden sztring enumerálási értéke érzéketlen a kis- és nagybetűknél.

HTTP-állapotkódok

Állapotkód	A következőkre vonatkozik:	Hibakategória	Description	Gyakori okok
200	Minden APIk	Success	A kérés sikeres volt.	-
202	Csak tallózás	Elfogadott	Feldolgozásra elfogadott kérés (élő bejárás).	Igény szerinti bejárás folyamatban
400	Minden APIk	Hibás kérés	Érvénytelen kérelemparaméterek.	Hiányzó kötelező mezők, érvénytelen paraméterértékek, hibásan formázott JSON
401	Minden APIk	Unauthorized	A hitelesítés sikertelen vagy hiányzik.	Érvénytelen API-kulcs, hiányzó x-apikey fejléc
403	Minden APIk	Forbidden	Érvényes hitelesítő adatok, de nem megfelelő engedélyek.	Az API-kulcs nem rendelkezik szükséges engedélyekkel
403	Csak tallózás	Forbidden	Szűrt tartalom vagy kizárva az URL-cím.	Szabályzat vagy szűrt tartalom által letiltott URL-cím
404	Csak tallózás	Nem található	A dokumentum nem található.	Érvénytelen vagy elérhetetlen URL-cím
410	Minden APIk	Eltűnt	HTTPS szükséges.	HTTPS helyett HTTP-en keresztül küldött kérelem
415	Minden APIk	Nem támogatott médiatípus	A tartalomtípus nem támogatott.	Hiányzó vagy helytelen content-type fejléc
429	Minden APIk	Túl sok kérés	Túllépte a sebességkorlátot.	Túl sok kérés az időablakban
430	Csak tallózás	Kiszolgálóhiba	Túl sok igény szerinti bejárás.	Túlzott élő bejárási kérelmek
500	Minden APIk	Belső kiszolgálóhiba	Váratlan kiszolgálóhiba.	Ideiglenes kiszolgálóval kapcsolatos probléma

Hibaválasz-struktúra

Az összes hibaválasz ezt a sémát követi:

Field	Típus	Description
errorCode	karakterlánc	Részletesebb hibakategória, amely segít azonosítani a hiba típusát.
errorCategory	karakterlánc	Magas szintű kategória: UserError (ügyféloldali / nem újrapróbálható) vagy SystemError (kiszolgálóoldali / újrapróbálkozható).
userMessage	karakterlánc	Emberi olvasásra alkalmas hibaleírás.
technicalDetails	karakterlánc (nem kötelező)	További műszaki információk vagy paraméterérvényesítési adatok a hibakereséshez.
retryAfter	karakterlánc (nem kötelező)	Várakozási idő az újrapróbálkozás előtt.
requestId	karakterlánc (nem kötelező)	A kérés egyedi azonosítója.
traceId	karakterlánc	Elosztott nyomkövetési azonosító hibakereséshez és Microsoft támogatáshoz.

Note

202 Accepted a válaszok (például az élő bejárás lekérdezésének tallózása) nem hibaválaszok, és nem használják a fenti hibasémát. Továbbra is tartalmazhatnak egy retryAfter értéket, amely jelzi, hogy mikor kell újrapróbálkoznia a kérésnek.

Példa hibaválasz:

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

Hibakódok referenciája

Kérésérvényesítési hibák

Hibakód	HTTP-állapot	Category	Description
RequestInvalidFormat	400	UserError	Hibás JSON-törzs vagy érvénytelen kérelem hasznos adatszerkezete.
RequestInvalidMethod	400	UserError	Érvénytelen metódus vagy eszköznév van megadva a kérelemben.
HandlerInvalidInput	400	UserError	Érvénytelen bemeneti paraméterértékek (például üres lekérdezés, maxResults tartományon kívül [1, 50], érvénytelen számértékek).
RequestBlockedHeader	400	UserError	A kérelem tartalmaz egy letiltott hibakeresési/változatfejlécet (pl. X-Augmentations, , X-XapHostOverrideX-DebugOptions). Ehelyett használjon dokumentált URL-paramétereket (?p1=, ?debugoptions=, ?atlahostname=) .
RequestUnsupportedMediaType	415	UserError	A content-type fejléc hiányzik vagy sem application/json.
MethodNotAllowed	405	UserError	Az útvonalon nem engedélyezett HTTP-metódus (pl. GET egy csak POST-végponton).

Hitelesítési és engedélyezési hibák

Hibakód	HTTP-állapot	Category	Description
AuthNoToken	401	UserError	Hitelesítés szükséges. Nincs megadva tulajdonosi jogkivonat vagy API-kulcs.
AuthTokenParse	401	UserError	Érvénytelen hitelesítési jogkivonat-formátum vagy jogkivonat-elemzés nem sikerült.
AuthInvalidApiKey	401	UserError	A megadott API-kulcs érvénytelen vagy nem felismerhető.
AuthenticationFailed	401	UserError	Általános hitelesítési hiba.
AuthExpiredTrial	401	UserError	A próbaidőszak lejárt. Frissítse a kulcsot.
AuthMissingEntryId	400	UserError	Hiányzó alkalmazásidentitás/ bejegyzésazonosító a kérelemkörnyezetben.
AuthAppIdSelectionRequired	400	UserError	Az identitás több alkalmazásra is leképzendő. Adja meg a célalkalmazást a lekérdezési APPID paraméterrel. Lásd: Több AppID hívása.
AuthUnauthorizedEntryId	401	UserError	Jogosulatlan belépési azonosító. Az alkalmazásidentitás nem oldható fel, vagy a APPID lekérdezési paraméter API-kulcsos hitelesítéssel lett elküldve.
AuthUnauthorizedAppId	403	UserError	A megadott APPID nincs társítva az identitással.
AuthUnauthorizedService	403	UserError	A hívó hitelesítéssel rendelkezik, de nem fér hozzá a kért szolgáltatáshoz/függőlegeshez.
AuthBatchEndpointRequired	403	UserError	A webes kereséshez a batch végpont (X-FD-Batch: 1) használatához alkalmazás szükséges.
AuthMcpWebForbidden	403	UserError	Az alkalmazás nem használhatja az MCP web eszközt.
AuthContentFormatForbidden	403	UserError	Ez az alkalmazás csak átjárókhoz rendelkezik hozzáféréssel. Használja contentFormatpassagea . Lásd : Szakaszok és tartalomformátumok.

Sebességkorlátozó hibák

Hibakód	HTTP-állapot	Category	Description
AuthUserThrottled	429	UserError	A kérelmek gyakorisága meghaladja az erőforrás sebességkorlátját. Ellenőrizze a retryAfterelemet.
AuthUserDailyUsageExceeded	429	UserError	Elérte a napi kérelemkvótát (alaphelyzetbe állítás UTC 00:00-kor). Ellenőrizze a retryAfterelemet.

Az API-specifikus hibák tallózása

Hibakód	HTTP-állapot	Category	Description
BrowseApiDocNotFound	404	UserError	A dokumentum nem található. A megadott URL-címhez nem érhető el tartalom.
BrowseApiIsFilteredOut	403	UserError	Az eredmény elvetése szabályzat vagy tartalomszűrés miatt történt.
BrowseApiIsUrlExcluded	403	UserError	A cél URL-címet a szabályzat kizárja vagy letiltja.
BrowseApiTooManyOnDemandCrawls	430	UserError	Túl sok igény szerinti élő bejárási kérés van folyamatban.

Szolgáltatás- és infrastruktúrahibák

Hibakód	HTTP-állapot	Category	Újrapróbálható	Description
InternalServerError	500	SystemError	Igen (30-as)	Belső kiszolgálóhiba.

Gyakori hibaforgatókönyvek

Hitelesítési hibák (401, 403)

Tünet: A hitelesítés sikertelen vagy tiltott hozzáférés

Megoldások:

• Ellenőrizze, hogy az API-kulcs helyes-e, és szerepel-e a x-apikey fejlécben
• Ellenőrizze, hogy az API-kulcs nem járt-e le
• Győződjön meg arról, hogy rendelkezik a végponthoz szükséges engedélyekkel
• Ha a problémák továbbra is fennállnak, forduljon a Microsoft képviselőjéhez

Példa:

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

Sebességkorlátozás (429)

Tünet: Túllépte a sebességkorlátot, vagy kimerült a napi kvóta (AuthUserThrottled vagy AuthUserDailyUsageExceeded)

Az erőforrás sebességkorlátja feletti kérések HTTP 429-et adnak vissza. A sebességkorlát a webes IQ-portálon jelenik meg.

Megoldások:

• Exponenciális visszalépéses újrapróbálkozási logika implementálása
• Várja meg az időközt retryAfter a hibaválaszban (pl. "60s") az újrapróbálkozás előtt
• Kérelem gyakoriságának csökkentése
• Vegye figyelembe, hogy a napi kvótakorlátok (AuthUserDailyUsageExceeded) alaphelyzetbe állítása naponta 00:00 (UTC) időpontban
• Ha magasabb korlátot szeretne kérni, forduljon a webes IQ-támogatáshoz

Példa válasz:

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

Érvénytelen paraméterek (400)

Tünet: Érvénytelen paraméterek miatt hibás kérés

Gyakori problémák:

• Hiányzó kötelező mezők (például query paraméter)
• Tartományon kívüli paraméterértékek (pl. maxResults> 50)
• Érvénytelen paramétertípusok (például egész szám helyett sztring)
• Nem támogatott paraméterértékek (például érvénytelen contentFormat)

Megoldások:

• Ellenőrizze, hogy az összes szükséges paraméter megtalálható-e
• Paraméterértékek ellenőrzése dokumentált megkötések alapján
• A megfelelő JSON-formázás biztosítása

Kiszolgáló- és infrastruktúrahibák (500)

Tünet: Váratlan belső kiszolgáló- vagy felsőbb rétegbeli szolgáltatáshiba (InternalServerError)

Megoldások:

• Ellenőrizze a retryAfter mezőt (alapértelmezés szerint ) "30s"és próbálkozzon újra a kéréssel a várakozás után
• Újrapróbálkozás implementálása exponenciális visszalépéssel és jitterrel
• Ha a probléma továbbra is fennáll, forduljon Microsoft ügyfélszolgálatához a traceId válaszban megadott

Példa válasz:

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

Az API által elfogadott válasz tallózása (202)

Tünet: Elfogadott válasz mezővel retryAfter

Magyarázat: Ha liveCrawl "tartalék" értékre van állítva, és az URL-címet be kell járni, az API a 202 Accepted értéket adja vissza, retryAfter amely jelzi, hogy mikor kell újrapróbálkoznia a kérésnek.

Kezelés:

# 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

Bevált gyakorlatok

1. Mindig ellenőrizze az állapotkódokat – Ne feltételezze a sikert
2. A traceId használata a támogatáshoz – A traceId belefoglalása a támogatási szolgálathoz való kapcsolódáskor
3. Újrapróbálkozási logika implementálása – Exponenciális visszalépés használata átmeneti hibák esetén
4. 202 válasz kezelése – Élő bejárással, várakozással és újrapróbálkozással rendelkező Browse API
5. Ellenőrzés küldés előtt – Paraméterek helyi ellenőrzése a 400 hiba elkerülése érdekében
6. Csak HTTPS használata – A HTTP-kérések 410 hibát adnak vissza