Microsoft Web IQ-Fehlerbehandlung

Alle v3-APIs geben standardisierte Fehlerantworten zurück, um Probleme schnell zu diagnostizieren und zu beheben. In diesem Abschnitt werden HTTP-Statuscodes, Fehlerantwortstruktur und allgemeine Problembehandlungsszenarien behandelt.

Note

Bei allen Zeichenfolgenumwerten wird die Groß-/Kleinschreibung beachtet.

HTTP-Statuscodes

Statuscode	Gilt für	Fehlerkategorie	Description	Häufige Ursachen
200	Alle APIs	Success	Die Anfrage war erfolgreich.	-
202	Nur durchsuchen	Akzeptiert	Anforderung für die Verarbeitung akzeptiert (Live-Durchforstung).	On-Demand-Durchforstung wird ausgeführt
400	Alle APIs	Ungültige Anforderung	Ungültige Anforderungsparameter.	Fehlende erforderliche Felder, ungültige Parameterwerte, falsch formatierter JSON-Code
401	Alle APIs	Unauthorized	Fehler bei der Authentifizierung oder fehlender Authentifizierung.	Ungültiger API-Schlüssel, fehlender x-apikey-Header
403	Alle APIs	Verboten	Gültige Anmeldeinformationen, aber unzureichende Berechtigungen.	API-Schlüssel verfügt nicht über erforderliche Berechtigungen
403	Nur durchsuchen	Verboten	Inhalt gefiltert oder URL ausgeschlossen.	Url, die durch Richtlinie oder gefilterte Inhalte blockiert wird
404	Nur durchsuchen	Nicht gefunden	Das Dokument wurde nicht gefunden.	Ungültige oder nicht zugängliche URL
410	Alle APIs	Nicht vorhanden (Gone)	HTTPS erforderlich.	Anforderung über HTTP anstelle von HTTPS
415	Alle APIs	Nicht unterstützter Medientyp	Der Inhaltstyp wird nicht unterstützt.	Fehlende oder falsche content-type Kopfzeile
429	Alle APIs	Zu viele Anforderungen	Das Ratenlimit wurde überschritten.	Zu viele Anforderungen im Zeitfenster
430	Nur durchsuchen	Serverfehler	Zu viele On-Demand-Durchforstungen.	Übermäßige Live-Durchforstungsanforderungen
500	Alle APIs	Interner Serverfehler	Unerwarteter Serverfehler.	Temporäres Serverproblem

Struktur von Fehlerantworten

Alle Fehlerantworten folgen diesem Schema:

Feld	Typ	Description
errorCode	string	Eine detailliertere Fehlerkategorie, die hilft, den Typ des Fehlers zu identifizieren.
errorCategory	string	Allgemeine Kategorie: UserError (clientseitige / nicht retryable) oder SystemError (serverseitige / wiederholungsfähig).
userMessage	string	Für Menschen lesbare Fehlerbeschreibung.
technicalDetails	String (optional)	Zusätzliche technische Informationen oder Parameterüberprüfungsdetails für das Debuggen.
retryAfter	String (optional)	Zeit bis zum Erneuten Wiederholen.
requestId	String (optional)	Eindeutiger Bezeichner für die Anforderung.
traceId	string	Verteilte Ablaufverfolgungs-ID zum Debuggen und Microsoft Unterstützung.

Note

202 Accepted Antworten (z. B. Durchsuchen von Livedurchforstungsumfragen) sind keine Fehlerantworten und verwenden das obige Fehlerschema nicht. Sie können weiterhin einen retryAfter Wert enthalten, der angibt, wann die Anforderung erneut versucht werden soll.

Beispielfehlerantwort:

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

Fehlercodesreferenz

Fehler bei der Anforderungsüberprüfung

Fehlercode	HTTP-Status	Category	Description
RequestInvalidFormat	400	UserError	Falsch formatierter JSON-Textkörper oder ungültige Anforderungsnutzlaststruktur.
RequestInvalidMethod	400	UserError	Ungültiger Methoden- oder Toolname, der in der Anforderung angegeben ist.
HandlerInvalidInput	400	UserError	Ungültige Eingabeparameterwerte (z. B. leere Abfrage, maxResults außerhalb des Bereichs [1, 50], ungültige Enumerationswerte).
RequestBlockedHeader	400	UserError	Die Anforderung enthält einen blocklisteten Debug-/Variant-Header (z. B. X-Augmentations, , X-DebugOptions). X-XapHostOverride Verwenden Sie stattdessen dokumentierte URL-Parameter (?p1=, ?debugoptions=, ?atlahostname=).
RequestUnsupportedMediaType	415	UserError	Die content-type Kopfzeile fehlt oder nicht application/json.
MethodNotAllowed	405	UserError	HTTP-Methode ist für die Route nicht zulässig (z. B. GET auf einem NUR POST-Endpunkt).

Authentifizierungs- und Autorisierungsfehler

Fehlercode	HTTP-Status	Category	Description
AuthNoToken	401	UserError	Authentifizierung erforderlich. Kein Bearertoken oder API-Schlüssel bereitgestellt.
AuthTokenParse	401	UserError	Ungültiges Authentifizierungstokenformat oder Tokenanalysefehler.
AuthInvalidApiKey	401	UserError	Der bereitgestellte API-Schlüssel ist ungültig oder nicht erkannt.
AuthenticationFailed	401	UserError	Allgemeiner Authentifizierungsfehler.
AuthExpiredTrial	401	UserError	Der Testzeitraum ist abgelaufen. Bitte aktualisieren Sie Ihren Schlüssel.
AuthMissingEntryId	400	UserError	Fehlende Anwendungsidentität/Eintrags-ID im Anforderungskontext.
AuthAppIdSelectionRequired	400	UserError	Ihre Identität ist mehreren Anwendungen zugeordnet. Geben Sie die Zielanwendung mithilfe des APPID Abfrageparameters an. Weitere Informationen finden Sie unter Aufrufen mehrerer AppID.
AuthUnauthorizedEntryId	401	UserError	Nicht autorisierte Eintrags-ID. Die Anwendungsidentität konnte nicht aufgelöst werden, oder der APPID Abfrageparameter wurde mit API-Schlüsselauthentifizierung gesendet.
AuthUnauthorizedAppId	403	UserError	Die angegebene APPID Angabe ist ihrer Identität nicht zugeordnet.
AuthUnauthorizedService	403	UserError	Der Anrufer wird authentifiziert, aber nicht autorisiert, um auf den angeforderten Dienst/die angeforderte Vertikale zuzugreifen.
AuthBatchEndpointRequired	403	UserError	Die Anwendung ist erforderlich, um den Batchendpunkt (X-FD-Batch: 1) für die Websuche zu verwenden.
AuthMcpWebForbidden	403	UserError	Die Anwendung darf das MCP-Tool web nicht verwenden.
AuthContentFormatForbidden	403	UserError	Diese Anwendung hat nur Zugriff auf Passagen. Verwenden Sie contentFormatpassage. Siehe Passagen und Inhaltsformate.

Fehler beim Einschränken von Raten

Fehlercode	HTTP-Status	Category	Description
AuthUserThrottled	429	UserError	Die Anforderungshäufigkeit überschreitet das Ratelimit Ihrer Ressource. Markieren Sie retryAfter.
AuthUserDailyUsageExceeded	429	UserError	Das tägliche Anforderungskontingent wurde erreicht (Setzt um 00:00 UTC zurück). Markieren Sie retryAfter.

API-spezifische Fehler durchsuchen

Fehlercode	HTTP-Status	Category	Description
BrowseApiDocNotFound	404	UserError	Das Dokument wurde nicht gefunden. Für die angegebene URL sind keine Inhalte verfügbar.
BrowseApiIsFilteredOut	403	UserError	Das Ergebnis wurde aufgrund von Richtlinien- oder Inhaltsfilterung verworfen.
BrowseApiIsUrlExcluded	403	UserError	Die Ziel-URL wird von der Richtlinie ausgeschlossen oder unzulässig.
BrowseApiTooManyOnDemandCrawls	430	UserError	Zu viele On-Demand-Live-Durchforstungsanforderungen werden ausgeführt.

Dienst- und Infrastrukturfehler

Fehlercode	HTTP-Status	Category	Wiederholbar	Description
InternalServerError	500	SystemError	Ja (30s)	Interner Serverfehler.

Häufige Fehlerszenarien

Authentifizierungsfehler (401, 403)

Symptom: Fehler bei der Authentifizierung oder unzulässiger Zugriff

Lösungen :

• Überprüfen, ob der API-Schlüssel korrekt ist und in den x-apikey Header eingeschlossen ist
• Überprüfen Sie, ob Ihr API-Schlüssel nicht abgelaufen ist.
• Stellen Sie sicher, dass Sie über die erforderlichen Berechtigungen für den Endpunkt verfügen.
• Wenden Sie sich an Ihren Microsoft Vertreter, wenn Probleme weiterhin bestehen.

Beispiel:

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

Zinsbegrenzung (429)

Symptom: Satzgrenze überschritten oder tageskontingent überschritten (AuthUserThrottled oder AuthUserDailyUsageExceeded)

Anforderungen über dem Grenzwert für die Rate ihrer Ressource geben HTTP 429 zurück. Ihr Zinslimit wird im Web IQ-Portal angezeigt.

Lösungen :

• Exponentielle Backoff-Wiederholungslogik implementieren
• Warten Sie auf das retryAfter Intervall in der Fehlerantwort (z. B. "60s"), bevor Sie den Vorgang wiederholen.
• Verringern der Anforderungshäufigkeit
• Beachten Sie, dass tägliche Kontingentgrenzen (AuthUserDailyUsageExceeded) täglich um 00:00 UTC zurückgesetzt werden
• Um eine höhere Grenze anzufordern, wenden Sie sich an den Web IQ Support

Beispielantwort:

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

Ungültige Parameter (400)

Symptom: Ungültige Anforderung aufgrund ungültiger Parameter

Allgemeine Probleme:

• Erforderliche Felder fehlen (z. B. query Parameter)
• Parameterwerte außerhalb des Bereichs (z. B. maxResults> 50)
• Ungültige Parametertypen (z. B. Zeichenfolge anstelle ganzzahliger Zahlen)
• Nicht unterstützte Parameterwerte (z. B. ungültig contentFormat)

Lösungen :

• Überprüfen, ob alle erforderlichen Parameter vorhanden sind
• Überprüfen von Parameterwerten anhand dokumentierter Einschränkungen
• Sicherstellen der richtigen JSON-Formatierung

Server- und Infrastrukturfehler (500)

Symptom: Unerwarteter interner Server- oder Upstreamdienstfehler (InternalServerError)

Lösungen :

• Überprüfen Sie das retryAfter Feld (standardeinstellung) "30s"und wiederholen Sie die Anforderung nach dem Warten.
• Wiederholungsversuche mit exponentiellem Backoff und Jitter implementieren
• Wenn das Problem weiterhin besteht, wenden Sie sich an den support Microsoft mit der traceId in der Antwort bereitgestellten

Beispielantwort:

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

Akzeptierte API-Antwort durchsuchen (202)

Symptom: Akzeptierte Antwort mit retryAfter Feld

Erläuterung: Wenn liveCrawl sie auf "Fallback" festgelegt ist und die URL durchforstet werden muss, gibt die API "202 Akzeptiert" mit einem retryAfter Wert zurück, der angibt, wann die Anforderung erneut versucht werden soll.

Handhabung:

# 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

Bewährte Vorgehensweisen

1. Statuscodes immer überprüfen – Kein Erfolg annehmen
2. Use traceId for support - Include traceId when contacting support
3. Implementieren von Wiederholungslogik – Verwenden eines exponentiellen Backoffs für vorübergehende Fehler
4. Behandeln von 202 Antworten – Für die Such-API mit Live-Durchforstung warten und wiederholen
5. Überprüfen vor dem Senden – Überprüfen Von Parametern lokal, um 400 Fehler zu vermeiden
6. Nur HTTPS verwenden – HTTP-Anforderungen geben 410 Fehler zurück.