Résoudre les problèmes liés aux API REST Microsoft Fabric

Présentation

Cet article vous aide à comprendre et à résoudre les erreurs courantes retournées par les API REST Microsoft Fabric. Il explique le format d’erreur standard utilisé par le service et fournit des conseils pour résoudre les codes d’état HTTP les plus fréquemment rencontrés.

Comprendre les réponses d’erreur Microsoft Fabric

Lorsqu’une erreur se produit lors du traitement d’une requête vers l’API REST Microsoft Fabric, le service retourne un objet standard ErrorResponse dans le corps de la réponse.

Lors du dépannage, capturez et consignez toujours requestId car il identifie de façon unique la demande et est requis lors du contact avec le support Microsoft. L’ID de requête est disponible à la fois dans le corps de la réponse et dans les en-têtes de réponse.

Important

  • errorCode les valeurs sont stables et basées sur un contrat.
  • Le texte lisible message par l’homme peut changer au fil du temps et ne doit pas être analysé par programme.

Schéma ErrorResponse

Nom Type Descriptif
errorCode string Identificateur stable pour la condition d’erreur. Utilisez cette valeur lors de l’implémentation de la logique de gestion des erreurs.
message string Une description de l’erreur à l’intention des utilisateurs.
moreDetails ErrorResponseDetails[] Liste facultative des détails d’erreur supplémentaires.
relatedResource ErrorRelatedResource Informations sur la ressource associée à l’erreur, le cas échéant.
requestId string Identificateur unique de la requête ayant échoué. Incluez cette valeur lors du contact avec le support Microsoft.

schéma ErrorResponseDetails

Fournit un contexte supplémentaire pour les scénarios d’erreur complexes.

Nom Type Descriptif
errorCode string Identificateur stable décrivant les détails d’erreur spécifiques.
message string Explication lisible par l’homme du détail de l’erreur.
relatedResource ErrorRelatedResource Ressource associée à ce détail d’erreur spécifique.

Schéma ErrorRelatedResource

Identifie la ressource impliquée dans l’erreur.

Nom Type Descriptif
resourceId string ID de la ressource impliquée dans l’erreur.
resourceType string Type de la ressource (par exemple, espace de travail, élément ou capacité).

Scénarios d’erreur HTTP courants

Les sections suivantes décrivent les codes d’état HTTP courants retournés par les API REST Microsoft Fabric, ainsi que les causes racines classiques et les résolutions recommandées.

L’API retourne 401 – Non autorisé

Une réponse 401 indique que la demande a échoué pendant la validation du jeton d’authentification ou d’accès.

Principales causes courantes

Code d’erreur Descriptif Résolution
TokenExpired Le jeton d’accès a expiré. Acquérir un nouveau jeton d’accès et réessayer la requête.
InsufficientScopes Le jeton d’accès n’inclut pas les périmètres requis. Mettez à jour l’application pour demander les étendues requises comme documentées dans la spécification de l’API ou mettez à jour l’inscription de l’application Microsoft Entra.

L’API retourne 403 – Interdit

Une réponse 403 indique que l’appelant est authentifié, mais n’a pas les autorisations suffisantes pour effectuer l’opération demandée sur la ressource cible.

Principales causes courantes

Code d’erreur Descriptif Résolution
InsufficientPrivileges L’appelant n’a pas les autorisations requises pour accéder à la ressource. Demandez à un administrateur d’espace de travail ou de ressource d’accorder suffisamment d’autorisations à l’utilisateur ou au principal de service appelant.

L’API retourne 404 – Introuvable

Une réponse 404 indique qu’une ressource demandée ou référencée n’existe pas ou n’est pas accessible à l’appelant.

Remarque

Les API individuelles peuvent définir des codes d’erreur supplémentaires spécifiques à l’API. Reportez-vous toujours à la spécification de l’API pour obtenir des détails faisant autorité.

Principales causes courantes

Code d’erreur Descriptif Résolution
WorkspaceNotFound L’espace de travail spécifié est introuvable. Vérifiez que l’ID d’objet de l’espace de travail correct a été fourni.
EntityNotFound La ressource demandée est introuvable. Vérifiez que l’ID de ressource correct a été fourni. L’entité manquante est identifiée dans le relatedResource champ de la réponse d’erreur.

L’API retourne 429 – Trop de requêtes

Une réponse 429 indique que la requête a fait l’objet d’une limitation de débit. Microsoft Fabric retourne un code d’état 429 pour deux raisons distinctes, chacune identifiée par un autre errorCode dans le corps de la réponse.

Principales causes courantes

Code d’erreur Descriptif Résolution
RequestBlocked Le taux de requêtes a dépassé les limites de limitation du débit du service. Attendez la durée spécifiée dans l’en-tête Retry-After avant de réessayer. Consultez Gérer la limitation du débit dans votre application.
CapacityLimitExceeded Le calcul (unités de capacité) consommés sur votre capacité a dépassé les limites de la référence SKU Fabric achetée. Relancez la requête ultérieurement. Consultez Gérer la limitation de capacité.

Limitation du débit (RequestBlocked)

Une RequestBlocked erreur indique que le taux de requête a dépassé les limites de limitation du service.

  • La limitation est appliquée par identité de l’appelant.
  • Les limites de débit sont généralement évaluées sur des fenêtres d’une minute.

Informations de temporisation des reprises

Lorsque la limitation du débit se produit, les informations de nouvelle tentative sont fournies à deux emplacements :

  • Corps de la réponse (message)
    Exemple :
    "Request is blocked by the upstream service until: 12/24/2025 17:02:20 (UTC)"

  • Retry-After En-tête de réponse HTTP
    Spécifie le nombre de secondes pendant lesquelles le client doit attendre avant de réessayer.

Préférez toujours l’en-tête Retry-After lors de l’implémentation de la logique de nouvelle tentative.

Gérer la limitation du débit dans votre application

Les applications doivent :

  • Détecter les réponses HTTP 429.
  • Analysez et respectez l’en-tête Retry-After .
  • Appliquez une stratégie de réessai limitée, telle que le retrait exponentiel avec jitter pour les scénarios à grande échelle.
  • Évitez les boucles de nouvelle tentative infinies.

Réduire la probabilité de limitation du taux

  • Utilisez les opérations en bloc et par lots quand elles sont disponibles.
  • Préférez les API de liste par rapport aux requêtes à ressource unique répétées.
  • Cachez les données fréquemment sollicitées, en particulier les métadonnées qui changent rarement.
  • Évitez les rafales de trafic en distribuant uniformément les requêtes au fil du temps.

Limite de capacité dépassée (CapacityLimitExceeded)

Une erreur CapacityLimitExceeded indique que la puissance de calcul (unités de capacité) consommée par votre capacité a dépassé les limites du SKU Fabric acheté. Contrairement à la limitation de débit, cette limitation n’est pas due au nombre d’appels d’API effectués par un appelant spécifique ; elle reflète le calcul global consommé sur toutes les charges de travail sur la capacité.

Exemple de corps de réponse :

"Your organization's Fabric compute capacity has exceeded its limits. Try again later."

Gérer le bridage de capacité

Étant donné que cette limitation dépend des ressources de calcul globales consommées sur votre capacité plutôt que de votre taux de requêtes individuel, l’en-tête Retry-After n’est pas applicable, et une nouvelle tentative immédiate a peu de chances d’aboutir tant que l’utilisation des ressources de calcul de la capacité n’est pas redescendue dans les limites autorisées. Les applications doivent :

  • Réessayez la requête plus tard en utilisant une politique de nouvelle tentative bornée avec temporisation exponentielle.
  • Si l’erreur persiste, envisagez d’augmenter ou d’étendre votre capacité Fabric.

Pour plus d’informations sur les unités de capacité, les SKU et la façon dont la capacité Fabric est consommée, consultez Planifier la taille de votre capacité.

Résumé

La création d’intégrations fiables avec les API REST Microsoft Fabric nécessite une gestion des erreurs robuste et des modèles de requête efficaces. En comprenant les réponses aux erreurs, en respectant les signaux de limitation et en optimisant les modèles de requête, vous pouvez créer des applications résilientes.

Contenu connexe

Pour obtenir des questions supplémentaires ou des conseils de la communauté, consultez Microsoft Fabric Community

  • Last updated on