Microsoft gestion des erreurs Web IQ

Toutes les API v3 retournent des réponses d’erreur standardisées pour vous aider à diagnostiquer et résoudre rapidement les problèmes. Cette section traite des codes d’état HTTP, de la structure de réponse aux erreurs et des scénarios de résolution des problèmes courants.

Codes d’état HTTP

Les états 520, 523 et 524 font partie des codes d’erreur De navigation granulaires activés par défaut.

Structure de la réponse d’erreur

Toutes les réponses d’erreur suivent ce schéma :

Exemple de réponse d’erreur :

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

Informations de référence sur les codes d’erreur

Erreurs de validation de requête

Erreurs d’authentification et d’autorisation

Erreurs de limitation de débit

Parcourir les erreurs spécifiques à l’API

Les codes d’erreur granulaires sont activés par défaut pour Parcourir. Ils identifient la raison spécifique pour laquelle une page n’a pas pu être retournée, comme le filtrage de contenu, un document manquant ou un échec d’analyse, et incluent des conseils de nouvelle tentative le cas échéant. Aucune demande d’inscription ou de support n’est requise.

Les codes granulaires et hérités utilisent la structure de réponse d’erreur standard. Les erreurs de navigation qui ne sont pas répertoriées ici sont signalées comme InternalServerError (HTTP 500).

Codes d’erreur Parcourir hérités

Ces codes ont été utilisés avant que les codes d’erreur granulaires deviennent la valeur par défaut. Ils sont répertoriés pour référence lors de la gestion des réponses plus anciennes.

Codes d’erreur De navigation granulaire

Lorsqu’un délai de nouvelle tentative s’applique, la réponse inclut retryAfter en tant qu’horodatage UTC ISO 8601 au format yyyy-MM-ddTHH:mm:ssZ, par exemple "retryAfter": "2026-10-30T01:01:00Z". Ne réessayez pas avant cette heure. Lorsqu’il retryAfter est omis, aucune aide de nouvelle tentative ne s’applique.

Exemple de réponse d’erreur granulaire :

{
  "errorCode": "URLFilteredOutEncumbrance",
  "errorCategory": "UserError",
  "userMessage": "The requested URL was filtered by content restrictions.",
  "retryAfter": "2026-10-31T01:00:00Z",
  "traceId": "0123456789abcdef0123456789abcdef"
}

Parcourir les erreurs de passage

Ces erreurs s’appliquent aux requêtes Parcourir avec contentFormat: "passage", y compris les demandes des applications sans accès complet aux documents, pour lesquelles « passage » est le format par défaut. Consultez Parcourir les demandes de passage.

Tous les autres résultats parcourir pour les demandes de passage utilisent les mêmes codes d’état et codes d’erreur que text, htmlet markdown les demandes. Cela inclut les pages filtrées, les documents introuvables, une analyse dynamique en attente (202 Accepted) et des échecs d’analyse.

Erreurs de service et d’infrastructure

Scénarios d’erreurs courants

Erreurs d’authentification (401, 403)

Symptôme : Échec de l’authentification ou accès interdit

Solutions :

• Vérifiez que votre clé API est correcte et incluse dans l’en-tête x-apikey
• Vérifiez que votre clé API n’a pas expiré
• Vérifiez que vous disposez des autorisations requises pour le point de terminaison
• Contactez votre représentant Microsoft si les problèmes persistent

Exemple :

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

Limitation du débit (429)

Symptôme : Limite de débit dépassée ou quota quotidien épuisé (AuthUserThrottled ou AuthUserDailyUsageExceeded)

Les requêtes au-dessus de la limite de débit de votre AppID retournent HTTP 429. Votre limite de taux s’affiche dans le portail Web IQ.

Solutions :

• Implémenter une logique de nouvelle tentative avec temporisation exponentielle
• Attendez l’intervalle dans la retryAfter réponse d’erreur (par exemple, "60s") avant de réessayer
• Réduire la fréquence des demandes
• Notez que les limites de quota quotidiennes (AuthUserDailyUsageExceeded) sont réinitialisées quotidiennement à 00:00 UTC
• Pour demander une limite plus élevée, contactez le support web IQ

Exemple de réponse :

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

Paramètres non valides (400)

Symptôme : Demande incorrecte en raison de paramètres non valides

Problèmes courants

• Champs obligatoires manquants (par exemple, query paramètre)
• Valeurs des paramètres hors plage (par exemple, maxResults> 50)
• Types de paramètres non valides (par exemple, chaîne au lieu d’entier)
• Valeurs de paramètre non prises en charge (par exemple, non valides contentFormat)

Solutions :

• Valider tous les paramètres requis sont présents
• Vérifier les valeurs des paramètres par rapport aux contraintes documentées
• Garantir une mise en forme JSON appropriée

Erreurs de serveur et d’infrastructure (500)

Symptôme : Erreur inattendue du serveur interne ou du service en amont (InternalServerError)

Solutions :

• Vérifiez le retryAfter champ (par défaut "30s") et réessayez la requête après avoir attendu
• Implémenter une stratégie de nouvelle tentative avec temporisation exponentielle et gigue
• Si le problème persiste, contactez Microsoft support avec le traceId support fourni dans la réponse

Exemple de réponse :

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

Parcourir la réponse acceptée par l’API (202)

Symptôme : Réponse acceptée (202) avec url et retryAfter champs dans le corps de la réponse

Explication : Quand liveCrawl est « secours » et que l’URL n’est pas trouvée dans l’index, l’API peut démarrer une analyse de manière asynchrone et retourner 202 Accepté. L’analyse dynamique est soumise aux restrictions et à la disponibilité de l’éditeur ; La « secours » ne garantit pas une analyse réelle. Le même comportement s’applique à tous contentFormat, y compris passage.

Gestion :

1. Vérifiez l’état HTTP 202.
2. Lisez retryAfter le corps de la réponse. Il s’agit d’un horodatage UTC ISO 8601 (par exemple) "2026-10-30T01:01:00Z"qui est le plus tôt à réessayer.
3. Attendez jusqu’à ce moment-là.
4. Envoyez à nouveau la même requête. Le url champ contient l’URL à demander ; elle correspond par défaut à l’URL que vous avez demandée.
5. Limitez le nombre de tentatives d’interrogation. Une analyse qui ne peut pas se terminer retourne une erreur, telle que HostCrawlTimeout (524) ou FailedNoContent (520).

# 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", "contentFormat": "passage", "query": "information about this domain", "liveCrawl": "fallback"}'

# Example response when the URL isn't indexed: 202 Accepted with "retryAfter": "2026-10-30T01:01:00Z"
# Wait until that time, then send the same request again

Bonnes pratiques

1. Toujours vérifier les codes d’état - Ne supposez pas la réussite
2. Utiliser traceId pour la prise en charge - Inclure traceId lors du contact avec le support technique
3. Implémenter une logique de nouvelle tentative - Utiliser une interruption exponentielle pour les erreurs temporaires
4. Gérer les réponses 202 : pour l’API Parcourir avec analyse dynamique, patientez jusqu’à ce que le retryAfter temps et la nouvelle tentative
5. Gérer les deux retryAfter formats - Utilisez la durée pour AuthUserThrottled, AuthUserDailyUsageExceededet InternalServerError, et l’horodatage ISO 8601 pour Parcourir 202 et les erreurs granulaires, notamment TooManyOnDemandCrawls (429)
6. Valider avant l’envoi - Vérifier les paramètres localement pour éviter 400 erreurs
7. Utiliser HTTPS uniquement - Les requêtes HTTP retournent 410 erreurs