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.

Note

Toutes les valeurs d’énumération de chaîne ne respectent pas la casse.

Codes d’état HTTP

Code de statut	S’applique à	Catégorie d’erreur	Description	Causes courantes
200	Toutes les API	Success	La demande a abouti.	-
202	Parcourir uniquement	Accepté	Demande acceptée pour le traitement (analyse dynamique).	Analyse à la demande en cours
400	Toutes les API	Demande incorrecte	Paramètres de requête non valides.	Champs obligatoires manquants, valeurs de paramètre non valides, JSON mal formé
401	Toutes les API	Unauthorized	Échec ou absence de l’authentification.	Clé API non valide, en-tête x-apikey manquant
403	Toutes les API	Interdit	Informations d’identification valides, mais autorisations insuffisantes.	La clé API ne dispose pas des autorisations requises
403	Parcourir uniquement	Interdit	Contenu filtré ou URL exclu.	URL bloquée par stratégie ou contenu filtré
404	Parcourir uniquement	Introuvable	Document introuvable.	URL non valide ou inaccessible
410	Toutes les API	Non disponible (Gone)	HTTPS requis.	Requête effectuée sur HTTP au lieu de HTTPS
415	Toutes les API	Type de média non pris en charge	Type de contenu non pris en charge.	En-tête manquant ou incorrect content-type
429	Toutes les API	Trop de demandes	Limite de débit dépassée.	Trop de requêtes dans la fenêtre de temps
430	Parcourir uniquement	Erreur du serveur	Trop d’analyses à la demande.	Demandes d’analyse dynamique excessives
500	Toutes les API	Erreur interne du serveur	Erreur de serveur inattendue.	Problème de serveur temporaire

Structure de la réponse d’erreur

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

Champ	Type	Description
errorCode	string	Catégorie d’erreur plus détaillée qui permet d’identifier le type d’erreur.
errorCategory	string	Catégorie de haut niveau : UserError (côté client / non retenable) ou SystemError (côté serveur / retentable).
userMessage	string	Description lisible de l’erreur.
technicalDetails	chaîne (facultatif)	Informations techniques supplémentaires ou détails de validation des paramètres pour le débogage.
retryAfter	chaîne (facultatif)	Délai d’attente avant de réessayer.
requestId	chaîne (facultatif)	Identificateur unique de la requête.
traceId	string	ID de trace distribué pour le débogage et Microsoft prise en charge.

Note

202 Accepted Les réponses (par exemple, Parcourir l’interrogation d’analyse dynamique) ne sont pas des réponses d’erreur et n’utilisent pas le schéma d’erreur ci-dessus. Ils peuvent toujours inclure une retryAfter valeur pour indiquer quand réessayer la demande.

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

Code d’erreur	État HTTP	Category	Description
RequestInvalidFormat	400	UserError	Corps JSON mal formé ou structure de charge utile de requête non valide.
RequestInvalidMethod	400	UserError	Nom de méthode ou d’outil non valide spécifié dans la requête.
HandlerInvalidInput	400	UserError	Valeurs de paramètre d’entrée non valides (par exemple, requête vide, maxResults hors plage [1, 50], valeurs d’énumération non valides).
RequestBlockedHeader	400	UserError	La requête contient un en-tête de débogage/variant bloqué (par exemple, , X-AugmentationsX-DebugOptions, X-XapHostOverride). Utilisez les paramètres d’URL documentés (?p1=, ?debugoptions=, ?atlahostname=) à la place.
RequestUnsupportedMediaType	415	UserError	L’en-tête content-type est manquant ou non application/json.
MethodNotAllowed	405	UserError	Méthode HTTP non autorisée sur l’itinéraire (par exemple, GET sur un point de terminaison POST uniquement).

Erreurs d’authentification et d’autorisation

Code d’erreur	État HTTP	Category	Description
AuthNoToken	401	UserError	Authentification requise. Aucun jeton du porteur ni clé API fournie.
AuthTokenParse	401	UserError	Échec de l’analyse du jeton d’authentification ou du format de jeton d’authentification non valide.
AuthInvalidApiKey	401	UserError	La clé API fournie n’est pas valide ou n’est pas reconnue.
AuthenticationFailed	401	UserError	Échec général de l’authentification.
AuthExpiredTrial	401	UserError	La période d’essai a expiré. Mettez à niveau votre clé.
AuthMissingEntryId	400	UserError	Identité de l’application manquante / ID d’entrée dans le contexte de la demande.
AuthAppIdSelectionRequired	400	UserError	Votre identité est mappée à plusieurs applications. Spécifiez l’application cible à l’aide du APPID paramètre de requête. Voir Appeler plusieurs AppID.
AuthUnauthorizedEntryId	401	UserError	ID d’entrée non autorisé. L’identité de l’application n’a pas pu être résolue ou le paramètre de requête a été envoyé avec l’authentification APPID par clé API.
AuthUnauthorizedAppId	403	UserError	La valeur spécifiée APPID n’est pas associée à votre identité.
AuthUnauthorizedService	403	UserError	L’appelant est authentifié mais non autorisé à accéder au service/vertical demandé.
AuthBatchEndpointRequired	403	UserError	L’application est nécessaire pour utiliser le point de terminaison de lot (X-FD-Batch: 1) pour la recherche web.
AuthMcpWebForbidden	403	UserError	L’application n’est pas autorisée à utiliser l’outil MCP web .
AuthContentFormatForbidden	403	UserError	Cette application a uniquement accès aux passages. Utiliser contentFormatpassage. Consultez passages et formats de contenu.

Erreurs de limitation de débit

Code d’erreur	État HTTP	Category	Description
AuthUserThrottled	429	UserError	La fréquence des requêtes dépasse la limite de débit de votre ressource. Vérifiez retryAfter.
AuthUserDailyUsageExceeded	429	UserError	Le quota de demandes quotidiennes a été atteint (réinitialise à 00:00 UTC). Vérifiez retryAfter.

Parcourir les erreurs spécifiques à l’API

Code d’erreur	État HTTP	Category	Description
BrowseApiDocNotFound	404	UserError	Document introuvable. Aucun contenu disponible pour l’URL spécifiée.
BrowseApiIsFilteredOut	403	UserError	Le résultat a été supprimé en raison du filtrage de stratégie ou de contenu.
BrowseApiIsUrlExcluded	403	UserError	L’URL cible est exclue ou non autorisée par la stratégie.
BrowseApiTooManyOnDemandCrawls	430	UserError	Trop de demandes d’analyse dynamique à la demande en cours.

Erreurs de service et d’infrastructure

Code d’erreur	État HTTP	Category	Réessayable	Description
InternalServerError	500	SystemError	Oui (30s)	Erreur interne du serveur.

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 ressource 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 avec retryAfter le champ

Explication : Lorsqu’elle liveCrawl est définie sur « secours » et que l’URL doit être analysée, l’API retourne 202 Accepté avec une retryAfter valeur indiquant quand réessayer la requête.

Gestion :

# 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

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, attente et nouvelle tentative
5. Valider avant l’envoi - Vérifier les paramètres localement pour éviter 400 erreurs
6. Utiliser HTTPS uniquement - Les requêtes HTTP retournent 410 erreurs