Microsoft Web IQ-foutafhandeling

Alle v3-API's retourneren gestandaardiseerde foutreacties om u te helpen problemen snel vast te stellen en op te lossen. In deze sectie worden HTTP-statuscodes, structuur van foutreacties en veelvoorkomende scenario's voor probleemoplossing beschreven.

Note

Alle tekenreeksenumwaarden zijn hoofdlettergevoelig.

HTTP-statuscodes

Statuscode	Van toepassing op	Foutcategorie	Description	Veelvoorkomende oorzaken
200	Alle API’s	Success	Het verzoek slaagde.	-
202	Alleen bladeren	Accepted	Aanvraag geaccepteerd voor verwerking (live verkenning).	Verkennen op aanvraag wordt uitgevoerd
400	Alle API’s	Onjuiste aanvraag	Ongeldige aanvraagparameters.	Ontbrekende vereiste velden, ongeldige parameterwaarden, ongeldige JSON
401	Alle API’s	Niet geautoriseerd	Verificatie is mislukt of ontbreekt.	Ongeldige API-sleutel, ontbrekende x-apikey-header
403	Alle API’s	Verboden	Geldige referenties, maar onvoldoende machtigingen.	API-sleutel heeft geen vereiste machtigingen
403	Alleen bladeren	Verboden	Inhoud gefilterd of uitgesloten URL.	URL geblokkeerd door beleid of inhoud gefilterd
404	Alleen bladeren	Niet gevonden	Het document is niet gevonden.	Ongeldige of niet-toegankelijke URL
410	Alle API’s	Weg	HTTPS vereist.	Aanvraag via HTTP in plaats van HTTPS
415	Alle API’s	Niet-ondersteund mediatype	Inhoudstype wordt niet ondersteund.	Ontbrekende of onjuiste content-type header
429	Alle API’s	Te veel aanvragen	De snelheidslimiet is overschreden.	Te veel aanvragen in tijdvenster
430	Alleen bladeren	Serverfout	Te veel verkenningen op aanvraag.	Overmatige live verkenningsaanvragen
500	Alle API’s	Interne serverfout	Onverwachte serverfout.	Probleem met tijdelijke server

Foutreactiestructuur

Alle foutberichten volgen dit schema:

Veld	Type	Description
errorCode	string	Een gedetailleerdere foutcategorie waarmee u het type fout kunt identificeren.
errorCategory	string	Categorie op hoog niveau: UserError (clientzijde/ niet opnieuw kan worden geprobeerd) of SystemError (server-side/retryable).
userMessage	string	Beschrijving van door mensen leesbare fouten.
technicalDetails	tekenreeks (optioneel)	Aanvullende technische informatie of parametervalidatiedetails voor foutopsporing.
retryAfter	tekenreeks (optioneel)	Tijd om te wachten voordat u het opnieuw probeert.
requestId	tekenreeks (optioneel)	Unieke id voor de aanvraag.
traceId	string	Gedistribueerde tracerings-id voor foutopsporing en Microsoft ondersteuning.

Note

202 Accepted antwoorden (bijvoorbeeld bladeren door live verkenningspeiling) zijn geen foutreacties en maken geen gebruik van het bovenstaande foutschema. Ze kunnen nog steeds een retryAfter waarde bevatten om aan te geven wanneer de aanvraag opnieuw moet worden uitgevoerd.

Voorbeeld van foutreactie:

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

Naslaginformatie over foutcodes

Validatiefouten aanvragen

Foutcode	HTTP-status	Category	Description
RequestInvalidFormat	400	UserError	Ongeldige JSON-hoofdtekst of ongeldige structuur voor nettoladingen van aanvragen.
RequestInvalidMethod	400	UserError	Ongeldige methode of naam van het hulpprogramma die is opgegeven in de aanvraag.
HandlerInvalidInput	400	UserError	Ongeldige invoerparameterwaarden (bijvoorbeeld een lege query, maxResults buiten het bereik [1, 50], ongeldige enumwaarden).
RequestBlockedHeader	400	UserError	Aanvraag bevat een bloklijst met foutopsporing/variantheader (bijvoorbeeld X-Augmentations, X-DebugOptions, ). X-XapHostOverride Gebruik in plaats daarvan gedocumenteerde URL-parameters (?p1=, ?debugoptions=, ?atlahostname=).
RequestUnsupportedMediaType	415	UserError	De content-type header ontbreekt of niet application/json.
MethodNotAllowed	405	UserError	De HTTP-methode is niet toegestaan op de route (bijvoorbeeld GET op een ALLEEN-POST-eindpunt).

Verificatie- en autorisatiefouten

Foutcode	HTTP-status	Category	Description
AuthNoToken	401	UserError	Verificatie is vereist. Er is geen bearer-token of API-sleutel opgegeven.
AuthTokenParse	401	UserError	Ongeldige indeling van verificatietoken of tokenparsering is mislukt.
AuthInvalidApiKey	401	UserError	De opgegeven API-sleutel is ongeldig of niet herkend.
AuthenticationFailed	401	UserError	Algemene verificatiefout.
AuthExpiredTrial	401	UserError	De proefperiode is verlopen. Voer een upgrade uit van uw sleutel.
AuthMissingEntryId	400	UserError	Ontbrekende toepassings-id/vermeldings-id in aanvraagcontext.
AuthAppIdSelectionRequired	400	UserError	Uw identiteit wordt toegewezen aan meerdere toepassingen. Geef de doeltoepassing op met behulp van de APPID queryparameter. Zie Meer dan één AppID aanroepen.
AuthUnauthorizedEntryId	401	UserError	Niet-geautoriseerde vermeldings-id. De toepassings-id kan niet worden omgezet of de APPID queryparameter is verzonden met API-sleutelverificatie.
AuthUnauthorizedAppId	403	UserError	Het opgegeven APPID is niet gekoppeld aan uw identiteit.
AuthUnauthorizedService	403	UserError	De beller wordt geverifieerd, maar is niet gemachtigd om toegang te krijgen tot de aangevraagde service/verticaal.
AuthBatchEndpointRequired	403	UserError	De toepassing is vereist voor het gebruik van het batch-eindpunt (X-FD-Batch: 1) voor zoekopdrachten op internet.
AuthMcpWebForbidden	403	UserError	Toepassing is niet toegestaan om het MCP-hulpprogramma web te gebruiken.
AuthContentFormatForbidden	403	UserError	Deze toepassing heeft alleen toegang tot passages. Gebruik contentFormatpassage. Zie Passages en inhoudsindelingen.

Snelheidsbeperkingsfouten

Foutcode	HTTP-status	Category	Description
AuthUserThrottled	429	UserError	De aanvraagfrequentie overschrijdt de frequentielimiet van uw resource. Controleer retryAfter.
AuthUserDailyUsageExceeded	429	UserError	Het dagelijkse aanvraagquotum is bereikt (wordt opnieuw ingesteld om 00:00 UTC). Controleer retryAfter.

Door API-specifieke fouten bladeren

Foutcode	HTTP-status	Category	Description
BrowseApiDocNotFound	404	UserError	Het document is niet gevonden. Er is geen inhoud beschikbaar voor de opgegeven URL.
BrowseApiIsFilteredOut	403	UserError	Het resultaat is verwijderd vanwege beleid of inhoudsfiltering.
BrowseApiIsUrlExcluded	403	UserError	De doel-URL wordt uitgesloten of niet toegestaan door beleid.
BrowseApiTooManyOnDemandCrawls	430	UserError	Er worden te veel live verkenningsaanvragen op aanvraag uitgevoerd.

Service- en infrastructuurfouten

Foutcode	HTTP-status	Category	Opnieuw proberen	Description
InternalServerError	500	SystemError	Ja (30s)	Interne serverfout.

Veelvoorkomende foutscenario's

Verificatiefouten (401, 403)

Symptoom: Verificatie mislukte of verboden toegang

Oplossingen:

• Controleer of uw API-sleutel juist is en is opgenomen in de x-apikey header
• Controleer of uw API-sleutel niet is verlopen
• Zorg ervoor dat u over de vereiste machtigingen voor het eindpunt beschikt
• Neem contact op met uw Microsoft vertegenwoordiger als de problemen zich blijven voordoen

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

Snelheidsbeperking (429)

Symptoom: Frequentielimiet overschreden of dagelijks quotum uitgeput (AuthUserThrottled of AuthUserDailyUsageExceeded)

Aanvragen boven de frequentielimiet van uw resource retourneren HTTP 429. Uw frequentielimiet wordt weergegeven in de Web IQ-portal.

Oplossingen:

• Logica voor nieuwe pogingen met exponentiële wachttijdverhoging implementeren
• Wacht op het retryAfter interval in de foutreactie (bijvoorbeeld "60s") voordat u het opnieuw probeert
• Aanvraagfrequentie verlagen
• Houd er rekening mee dat dagelijkse quotumlimieten (AuthUserDailyUsageExceeded) dagelijks om 00:00 UTC opnieuw worden ingesteld
• Neem contact op met Web IQ Support om een hogere limiet aan te vragen

Voorbeeldantwoord:

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

Ongeldige parameters (400)

Symptoom: Ongeldige aanvraag vanwege ongeldige parameters

Algemene problemen:

• Vereiste velden ontbreken (bijvoorbeeld query parameter)
• Parameterwaarden buiten het bereik (bijvoorbeeld maxResults> 50)
• Ongeldige parametertypen (bijvoorbeeld tekenreeks in plaats van geheel getal)
• Niet-ondersteunde parameterwaarden (bijvoorbeeld ongeldig contentFormat)

Oplossingen:

• Controleer of alle vereiste parameters aanwezig zijn
• Parameterwaarden controleren op gedocumenteerde beperkingen
• De juiste JSON-opmaak controleren

Server- en infrastructuurfouten (500)

Symptoom: Onverwachte interne server- of upstreamservicefout (InternalServerError)

Oplossingen:

• Controleer het retryAfter veld (standaard ingesteld op "30s") en voer de aanvraag opnieuw uit na het wachten
• Retries implementeren met exponentiële back-off en jitter
• Als het probleem zich blijft voordoen, neemt u contact op met Microsoft ondersteuning bij het traceId antwoord

Voorbeeldantwoord:

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

Door api geaccepteerd antwoord bladeren (202)

Symptoom: Geaccepteerd antwoord met retryAfter veld

Uitleg: Wanneer liveCrawl deze is ingesteld op 'terugval' en de URL moet worden verkend, retourneert de API 202 Geaccepteerd met een retryAfter waarde die aangeeft wanneer de aanvraag opnieuw moet worden uitgevoerd.

Verwerking:

# 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

Aanbevolen procedures

1. Statuscodes altijd controleren - Niet aannemen dat de statuscodes zijn geslaagd
2. TraceId gebruiken voor ondersteuning - TraceId opnemen bij het contact opnemen met ondersteuning
3. Logica voor opnieuw proberen implementeren - Exponentieel uitstel gebruiken voor tijdelijke fouten
4. 202-antwoorden verwerken - Voor bladeren-API met live crawl, wacht en probeer het opnieuw
5. Valideren voordat u verzendt - Controleer de parameters lokaal om 400 fouten te voorkomen
6. Alleen HTTPS gebruiken - HTTP-aanvragen retourneren 410 fouten