Microsoft Felhantering av webb-IQ

Alla v3-API:er returnerar standardiserade felsvar som hjälper dig att diagnostisera och lösa problem snabbt. Det här avsnittet beskriver HTTP-statuskoder, felhanteringsstruktur och vanliga felsökningsscenarier.

Note

Alla stränguppräkningsvärden är skiftlägeskänsliga.

HTTP-statuskoder

Statuskod	Gäller för	Felkategori	Description	Vanliga orsaker
200	Alla API:er	Success	Begäran lyckades.	-
202	Bläddra endast	Accepted	Begäran har godkänts för bearbetning (direkt crawlning).	Crawlning på begäran pågår
400	Alla API:er	Felaktig förfrågan	Ogiltiga parametrar för begäran.	Obligatoriska fält saknas, ogiltiga parametervärden, felaktigt formaterad JSON
401	Alla API:er	Behörighet saknas	Autentiseringen misslyckades eller saknas.	Ogiltig API-nyckel, x-apikey-huvud saknas
403	Alla API:er	Ej tillåtet	Giltiga autentiseringsuppgifter men otillräckliga behörigheter.	API-nyckeln saknar nödvändiga behörigheter
403	Bläddra endast	Ej tillåtet	Innehåll som filtreras eller url exkluderas.	URL blockerad av princip eller innehåll filtrerat
404	Bläddra endast	Hittades inte	Dokumentet hittades inte.	Ogiltig eller otillgänglig URL
410	Alla API:er	Borta	HTTPS krävs.	Begäran som görs via HTTP i stället för HTTPS
415	Alla API:er	Medietyp som inte stöds	Innehållstypen stöds inte.	Sidhuvud saknas eller är felaktigt content-type
429	Alla API:er	För många begäranden	Hastighetsgränsen har överskridits.	För många begäranden i tidsfönstret
430	Bläddra endast	Serverfel	För många crawlningar på begäran.	Överdrivna direktkrypningsbegäranden
500	Alla API:er	Internt serverfel	Oväntat serverfel.	Problem med tillfällig server

Felhanteringsstruktur

Alla felsvar följer det här schemat:

Fält	Type	Description
errorCode	string	En mer detaljerad felkategori som hjälper dig att identifiera typen av fel.
errorCategory	string	Kategori på hög nivå: UserError (klientsidan/icke-återförsöksbar) eller SystemError (serversidan/återförsöksbar).
userMessage	string	Mänskligläsbar felbeskrivning.
technicalDetails	sträng (valfritt)	Ytterligare teknisk information eller parameterverifieringsinformation för felsökning.
retryAfter	sträng (valfritt)	Tid att vänta innan du försöker igen.
requestId	sträng (valfritt)	Unik identifierare för begäran.
traceId	string	Distribuerat spårnings-ID för felsökning och stöd för Microsoft.

Note

202 Accepted svar (t.ex. Bläddra i live-crawlning) är inte felsvar och använder inte felschemat ovan. De kan fortfarande innehålla ett retryAfter värde som anger när begäran ska försöka igen.

Exempel på felsvar:

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

Referens för felkoder

Valideringsfel för begäran

Felkod	HTTP-status	Category	Description
RequestInvalidFormat	400	UserError	Felaktig JSON-brödtext eller ogiltig struktur för nyttolast för begäran.
RequestInvalidMethod	400	UserError	Ogiltigt metod- eller verktygsnamn som anges i begäran.
HandlerInvalidInput	400	UserError	Ogiltiga indataparametervärden (t.ex. tom fråga, maxResults utom intervallet [1, 50], ogiltiga uppräkningsvärden).
RequestBlockedHeader	400	UserError	Begäran innehåller ett blocklisterat felsöknings-/varianthuvud (t.ex. X-Augmentations, X-DebugOptions, X-XapHostOverride). Använd dokumenterade URL-parametrar (?p1=, ?debugoptions=, ?atlahostname=) i stället.
RequestUnsupportedMediaType	415	UserError	Rubriken content-type saknas eller inte application/json.
MethodNotAllowed	405	UserError	HTTP-metoden tillåts inte på vägen (t.ex. GET på en POST-slutpunkt).

Autentiserings- och auktoriseringsfel

Felkod	HTTP-status	Category	Description
AuthNoToken	401	UserError	Autentisering krävs. Ingen ägartoken eller API-nyckel har angetts.
AuthTokenParse	401	UserError	Ogiltigt format för autentiseringstoken eller tokenparsning misslyckades.
AuthInvalidApiKey	401	UserError	Den angivna API-nyckeln är ogiltig eller känns inte igen.
AuthenticationFailed	401	UserError	Allmänt autentiseringsfel.
AuthExpiredTrial	401	UserError	Utvärderingsperioden har upphört att gälla. Uppgradera din nyckel.
AuthMissingEntryId	400	UserError	Programidentitet/post-ID saknas i begärandekontexten.
AuthAppIdSelectionRequired	400	UserError	Din identitet mappar till flera program. Ange målprogrammet med frågeparametern APPID . Mer än ett AppID finns i Anropa mer än ett AppID.
AuthUnauthorizedEntryId	401	UserError	Obehörigt post-ID. Det gick inte att matcha programidentiteten APPID eller så skickades frågeparametern med API-nyckelautentisering.
AuthUnauthorizedAppId	403	UserError	Den angivna APPID är inte associerad med din identitet.
AuthUnauthorizedService	403	UserError	Anroparen är autentiserad men obehörig att komma åt den begärda tjänsten/vertikalen.
AuthBatchEndpointRequired	403	UserError	Programmet krävs för att använda batchslutpunkten (X-FD-Batch: 1) för webbsökning.
AuthMcpWebForbidden	403	UserError	Programmet får inte använda MCP-verktyget web .
AuthContentFormatForbidden	403	UserError	Det här programmet har bara åtkomst till passager. Använd contentFormatpassage. Se Avsnitt och innehållsformat.

Hastighetsbegränsningsfel

Felkod	HTTP-status	Category	Description
AuthUserThrottled	429	UserError	Begärandefrekvensen överskrider resursens hastighetsgräns. Kontrollera retryAfter.
AuthUserDailyUsageExceeded	429	UserError	Kvoten för daglig begäran har nåtts (återställs kl. 00:00 UTC). Kontrollera retryAfter.

Bläddra bland API-specifika fel

Felkod	HTTP-status	Category	Description
BrowseApiDocNotFound	404	UserError	Dokumentet hittades inte. Det finns inget tillgängligt innehåll för den angivna URL:en.
BrowseApiIsFilteredOut	403	UserError	Resultatet togs bort på grund av princip- eller innehållsfiltrering.
BrowseApiIsUrlExcluded	403	UserError	Mål-URL:en undantas eller tillåts inte av principen.
BrowseApiTooManyOnDemandCrawls	430	UserError	För många live crawlningsbegäranden på begäran pågår.

Tjänst- och infrastrukturfel

Felkod	HTTP-status	Category	Omförsökbar	Description
InternalServerError	500	SystemError	Ja (30-talet)	Internt serverfel uppstod.

Vanliga felscenarier

Autentiseringsfel (401, 403)

Symptom: Autentiseringen misslyckades eller förbjöds

Lösningar:

• Kontrollera att DIN API-nyckel är korrekt och inkluderad i x-apikey rubriken
• Kontrollera att API-nyckeln inte har upphört att gälla
• Kontrollera att du har de behörigheter som krävs för slutpunkten
• Kontakta din Microsoft representant om problemen kvarstår

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

Hastighetsbegränsning (429)

Symptom: Hastighetsgränsen har överskridits eller den dagliga kvoten har förbrukats (AuthUserThrottled eller AuthUserDailyUsageExceeded)

Begäranden över resursens hastighetsgräns returnerar HTTP 429. Din hastighetsgräns visas i webb-IQ-portalen.

Lösningar:

• Implementera logik för återförsök med exponentiell fördröjning
• Vänta på retryAfter intervallet i felsvaret (t.ex. "60s") innan du försöker igen
• Minska begärandefrekvensen
• Observera att dagliga kvottak (AuthUserDailyUsageExceeded) återställs dagligen kl . 00:00 UTC
• Om du vill begära en högre gräns kontaktar du web-IQ-supporten

Exempelsvar:

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

Ogiltiga parametrar (400)

Symptom: Felaktig begäran på grund av ogiltiga parametrar

Vanliga problem:

• Obligatoriska fält saknas (t.ex. query parameter)
• Parametervärden ligger inte inom intervallet (t.ex. maxResults> 50)
• Ogiltiga parametertyper (t.ex. sträng i stället för heltal)
• Parametervärden som inte stöds (t.ex. ogiltiga contentFormat)

Lösningar:

• Verifiera att alla obligatoriska parametrar finns
• Kontrollera parametervärden mot dokumenterade begränsningar
• Se till att JSON-formateringen är korrekt

Server- och infrastrukturfel (500)

Symptom: Oväntat internt server- eller överordnat tjänstfel (InternalServerError)

Lösningar:

• Kontrollera fältet retryAfter (standardvärdet "30s") och försök igen när du har väntat
• Implementera återförsök med exponentiell backoff och jitter
• Om problemet kvarstår kontaktar du Microsoft supporten med det traceId som anges i svaret

Exempelsvar:

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

Bläddra bland api-godkända svar (202)

Symptom: Godkänt svar med retryAfter fält

Förklaring: När liveCrawl är inställt på "återställning" och URL:en måste crawlas returnerar API:et 202 Godkänd med ett retryAfter värde som anger när begäran ska försöka igen.

Hantering:

# 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

Regelverk

1. Kontrollera alltid statuskoder – Anta inte att det lyckas
2. Använd traceId för support – Inkludera traceId när du kontaktar supporten
3. Implementera logik för återförsök – Använd exponentiell backoff för tillfälliga fel
4. Hantera 202-svar – För Bläddra i API med live-crawlning väntar du och försöker igen
5. Verifiera innan du skickar – Kontrollera parametrar lokalt för att undvika 400 fel
6. Använd endast HTTPS – HTTP-begäranden returnerar 410 fel