Gestion des erreurs pour les API Excel

Cet article fournit des instructions générales et des suggestions pour gérer les erreurs retournées par les API Excel dans Microsoft Graph lorsqu’une requête envoyée via l’API échoue.

Types de réponses d’erreur

Les API Excel dans Microsoft Graph retournent deux types d’erreurs. La première est la réponse d’erreur régulière, qui ressemble à ce qui suit.

HTTP/1.1 <HTTP status code>
Content-type: application/json
Retry-After: <Cooldown duration in seconds> (optional)

{
  "error": <Error object>
}

Le second provient du modèle d’opération de longue durée, qui peut retourner un 200 OK code de status HTTP et failed une status d’opération dans le corps de la réponse, comme dans l’exemple suivant.

HTTP/1.1 200 OK
Content-type: application/json

{
  "status": "failed",
  "error": <Error object>
}

Pour ces deux réponses d’erreur, l’objet error a la structure suivante.

Remarque

Les réponses d’erreur suivent la définition de la spécification OData v4 pour les réponses d’erreur.

{
  "code": "string",
  "message": "string",
  "innerError": { "@odata.type": "odata.error" }
}

L’objet innerError peut contenir de manière récursive davantage d’objets innerError avec des codes d’erreur supplémentaires et plus spécifiques. Par exemple, l’objet error peut contenir des informations d’erreur plus détaillées dans le code et le message d’erreur de deuxième niveau, comme indiqué.

{
  "code": "Top-level error code",
  "message": "Top-level error message",
  "innerError": {
    "code": "Second-level error code",
    "message": "Second-level error message",
    "innerError": { "@odata.type": "odata.error" }
  }
}

Étapes de gestion des réponses aux erreurs

Les clients Microsoft Graph doivent utiliser les étapes suivantes pour gérer les erreurs qui se produisent avec les API Excel.

1. Déterminer s’il s’agit d’une erreur d’opération de longue durée

Avant de gérer une erreur, la première étape consiste à déterminer si la réponse d’erreur provient d’un modèle d’opération de longue durée ou d’un modèle normal. Une erreur d’opération de longue durée retourne un 200 OK code de status HTTP et failed une status d’opération dans le corps de la réponse. Une réponse d’erreur régulière retourne une erreur HTTP correspondante status code.

2. Analyser le code d’erreur de deuxième niveau

Pour le modèle d’opération de longue durée et le modèle normal, le client doit d’abord analyser les codes d’erreur de deuxième niveau requis et les gérer conformément aux instructions. Si vous le souhaitez, le client peut également gérer d’autres codes d’erreur de second niveau ou choisir de revenir aux codes d’erreur de niveau supérieur ou aux codes status.

Les codes d’erreur ne respectent pas la casse.

Codes d’erreur de deuxième niveau requis

Le tableau suivant répertorie des instructions pour les codes d’erreur de deuxième niveau requis que les clients Microsoft Graph sont censés gérer. Le service peut ajouter de nouveaux codes d’erreur à tout moment.

Code	Instructions
accessConflict	La demande ayant échoué est en conflit avec d’autres clients qui accèdent au classeur (par exemple, un autre client a verrouillé le classeur pour modification). Le client Microsoft Graph n’est pas censé renvoyer la demande ayant échoué tant que le conflit n’est pas résolu. Un utilisateur final peut choisir d’effectuer manuellement les mêmes opérations avec Excel Online pour obtenir plus de détails sur le conflit.
badRequestUncategorized	Une erreur non spécifiée est trouvée dans la demande ayant échoué. Le client Microsoft Graph n’est pas censé renvoyer la demande ayant échoué.
conflictUncategorized	La demande ayant échoué est en conflit avec certains états du serveur. Le client Microsoft Graph n’est pas censé renvoyer la demande ayant échoué tant que le conflit n’est pas résolu. Un utilisateur final peut choisir d’effectuer manuellement les mêmes opérations avec Excel Online pour obtenir plus de détails sur le conflit.
forbiddenUncategorized	La demande ayant échoué n’est pas autorisée. Le client Microsoft Graph n’est pas censé renvoyer la demande ayant échoué. Un utilisateur final peut choisir d’effectuer manuellement les mêmes opérations avec Excel Online pour obtenir plus de détails sur les restrictions.
gatewayTimeoutUncategorized	Le service n’a pas pu effectuer la demande dans le délai imparti.
internalServerErrorUncategorized	Une erreur inconnue s’est produite. Le client Microsoft Graph n’est pas censé renvoyer la demande ayant échoué. Si une session est spécifiée dans la demande ayant échoué, un accès supplémentaire à la session n’est pas non plus attendu.
invalidSessionAccessConflict	La session spécifiée dans la demande n’est pas valide en raison de conflits avec d’autres clients qui accèdent au classeur (par exemple, un autre client a verrouillé le classeur pour modification). Un accès supplémentaire à la session spécifiée dans la demande ayant échoué n’est pas attendu. La recréation de sessions avec la même requête createSession n’est pas attendue tant que le conflit n’est pas résolu. La recréation de sessions avec une autre requête createSession peut ou non aboutir. Un utilisateur final peut choisir d’effectuer manuellement les mêmes opérations avec Excel Online pour obtenir plus de détails sur le conflit.
invalidSessionAuthentication	La session spécifiée dans la requête n’est pas valide en raison d’une erreur d’authentification. Un accès supplémentaire à la session spécifiée dans la demande ayant échoué n’est pas attendu. La recréation des sessions avec la même demande createSession n’est pas attendue tant que les informations d’authentification appropriées ne sont pas fournies.
invalidSessionNotFound	La session spécifiée dans la demande n’est pas valide, car le classeur est introuvable. Un accès supplémentaire à la session spécifiée dans la demande ayant échoué n’est pas attendu. La recréation de sessions avec la même requête createSession n’est pas attendue.
invalidSessionReCreatable	La session spécifiée dans la demande n’existe pas ou n’est pas valide en raison d’une erreur temporaire. Le client Microsoft Graph peut essayer de recréer une session et de reprendre le travail. Un accès supplémentaire à la session spécifiée dans la demande ayant échoué n’est pas attendu.
invalidSessionRestricted	La session spécifiée dans la requête n’est pas valide en raison de restrictions ou de configurations de service. Un accès supplémentaire à la session spécifiée dans la demande ayant échoué n’est pas attendu. La recréation de sessions avec la même demande createSession n’est pas attendue tant que les restrictions ou configurations bloquant la requête ne changent pas. La recréation de sessions avec une autre requête createSession peut ou non aboutir. Un utilisateur final peut choisir d’effectuer manuellement les mêmes opérations avec Excel Online pour obtenir plus de détails sur les restrictions.
invalidSessionUnexpected	La session spécifiée dans la requête n’est pas valide en raison d’un problème inattendu. Un accès supplémentaire à la session spécifiée dans la demande ayant échoué n’est pas attendu. La recréation de sessions avec la même requête createSession n’est pas attendue. La recréation de sessions avec une autre requête createSession peut ou non aboutir.
invalidSessionUnsupportedWorkbook	La session spécifiée dans la requête n’est pas valide, car le classeur contient des fonctionnalités non prises en charge ou dépasse la limite de taille. En règle générale, les facteurs non pris en charge sont introduits par un autre client accédant au classeur. Un accès supplémentaire à la session spécifiée dans la demande ayant échoué n’est pas attendu. La recréation de sessions avec la même requête createSession n’est pas attendue tant que les facteurs non pris en charge ne sont pas supprimés. La recréation de sessions avec une autre requête createSession peut ou non aboutir. Un utilisateur final peut choisir d’effectuer manuellement les mêmes opérations avec Excel Online pour obtenir plus de détails sur les facteurs non pris en charge, ou avec Excel Desktop où le classeur peut être pris en charge.
methodNotAllowedUncategorized	La méthode HTTP spécifiée dans la requête n’est pas autorisée sur la ressource. Le client Microsoft Graph n’est pas censé renvoyer la demande ayant échoué.
notFoundUncategorized	La ressource demandée est introuvable. Le client Microsoft Graph n’est pas censé renvoyer la demande ayant échoué.
notImplementedUncategorized	La fonctionnalité demandée n’est pas implémentée actuellement. Le client Microsoft Graph n’est pas censé renvoyer la demande ayant échoué.
payloadTooLargeUncategorized	La charge utile de la requête dépasse la limite de taille. Le client Microsoft Graph n’est pas censé renvoyer la demande ayant échoué.
serviceUnavailableUncategorized	Le service est temporairement indisponible ou surchargé. Le client Microsoft Graph n’est pas censé renvoyer la demande ayant échoué tant que la durée de refroidissement spécifiée n’est pas passée.
tooManyRequestsUncategorized	La demande ayant échoué dépasse certaines limites de fréquence. Le client Microsoft Graph n’est pas censé renvoyer la demande ayant échoué tant que la durée de refroidissement spécifiée n’est pas passée. Pour connaître les meilleures pratiques pour réduire la limitation, consultez Réduire les erreurs de limitation.
transientFailure	La demande a échoué en raison d’une erreur temporaire. Le client Microsoft Graph n’est pas censé renvoyer la demande ayant échoué tant que la durée de refroidissement spécifiée n’est pas passée.
unauthorizedUncategorized	Les informations d’authentification requises pour la ressource sont manquantes ou non valides. Le client Microsoft Graph n’est pas censé renvoyer la demande ayant échoué.
unsupportedWorkbook	La demande a échoué. Le classeur contient des fonctionnalités non prises en charge ou dépasse la limite de taille. Le client Microsoft Graph n’est pas censé renvoyer la demande ayant échoué tant que les facteurs non pris en charge n’ont pas été supprimés.

Remarque

Pour le modèle normal, la demande ayant échoué est définie comme la requête qui correspond à la réponse. Pour le modèle d’opération de longue durée, la demande ayant échoué est celle qui déclenche l’opération ayant échoué.

Exemples de code d’erreur de deuxième niveau facultatifs

Le tableau suivant répertorie des exemples de codes d’erreur de deuxième niveau facultatifs, y compris les instructions de gestion correspondantes pour chaque code d’erreur. Le service peut ajouter de nouveaux codes d’erreur à tout moment.

Code	Instructions
accessDenied	Vous ne pouvez pas effectuer l’opération demandée (par exemple, en effectuant des modifications sur des cellules verrouillées). Le client Microsoft Graph n’est pas censé renvoyer la demande ayant échoué.
filteredRangeConflict	L’opération a échoué car elle est en conflit avec une plage filtrée. Le client Microsoft Graph n’est pas censé renvoyer la demande ayant échoué.
generalException	Une erreur interne s’est produite lors du traitement de la demande. Le client Microsoft Graph n’est pas censé renvoyer la demande ayant échoué.
insertDeleteConflict	L’opération d’insertion ou de suppression tentée a créé un conflit. Le client Microsoft Graph n’est pas censé renvoyer la demande ayant échoué. Un utilisateur final peut choisir d’effectuer manuellement les mêmes opérations avec Excel Online pour obtenir plus de détails sur le conflit.
invalidArgument	L’argument n’est pas valide, est manquant ou a un format incorrect. Le client Microsoft Graph n’est pas censé renvoyer la demande ayant échoué.
invalidReference	Cette référence n’est pas valide pour l’opération en cours. Le client Microsoft Graph n’est pas censé renvoyer la demande ayant échoué.
itemAlreadyExists	La ressource en cours de création existe déjà. Le client Microsoft Graph n’est pas censé renvoyer la demande ayant échoué.
itemNotFound	La ressource demandée n’existe pas. Le client Microsoft Graph n’est pas censé renvoyer la demande ayant échoué.
methodNotAllowed	La méthode HTTP spécifiée dans la requête n’est pas autorisée sur la ressource. Le client Microsoft Graph n’est pas censé renvoyer la demande ayant échoué.
nonBlankCellOffSheet	Impossible d’insérer de nouvelles cellules, car cela pousserait les cellules non vides hors de la fin de la feuille de calcul. Le client Microsoft Graph n’est pas censé renvoyer la demande ayant échoué. Un utilisateur final peut supprimer des lignes ou des colonnes pour libérer de l’espace pour insérer du contenu, puis réessayer.
rangeExceedsLimit	Le nombre de cellules dans la plage a dépassé le nombre maximal pris en charge. Le client Microsoft Graph peut essayer d’envoyer une requête avec une plus petite taille de plage. Pour plus d’informations, voir Limites des ressources et optimisation des performances pour les compléments Office.
requestAborted	La requête a été abandonnée au moment de l’exécution, ce qui est généralement dû au calcul de temps long à partir de fonctions dans le classeur. Le client Microsoft Graph n’est pas censé renvoyer la demande ayant échoué.
unsupportedOperation	L’opération tentée n’est pas prise en charge. Le client Microsoft Graph n’est pas censé renvoyer la demande ayant échoué.

Remarque

Pour le modèle normal, la demande ayant échoué est définie comme la requête qui correspond à la réponse. Pour le modèle d’opération de longue durée, la demande ayant échoué est celle qui déclenche l’opération ayant échoué.

3. Analyser le code d’erreur de niveau supérieur

Si vous ne trouvez aucun code d’erreur de deuxième niveau connu, vous devez suivre les instructions fournies pour les erreurs de niveau supérieur. Les codes d’erreur de niveau supérieur sont liés au code status et vous pouvez prendre des mesures en fonction des codes de status correspondants. Pour plus d’informations sur les messages et codes d’erreur de niveau supérieur, consultez Codes d’erreur et messages.

4. Analyser le code status

Pour le modèle standard, si vous ne trouvez pas de code d’erreur de deuxième niveau ou de code d’erreur de niveau supérieur connu, vous devez prendre des mesures en fonction du code de status HTTP.

5. Récupération d’erreur de refroidissement

Pour certaines des réponses du modèle normal, une durée de refroidissement de récupération en secondes peut être fournie via un Retry-After en-tête. Lorsqu’une durée de récupération de récupération est présente, le client Microsoft Graph n’est pas censé envoyer de demandes de suivi avant l’expiration de la durée spécifiée. Pour connaître les meilleures pratiques relatives à l’en-tête et à Retry-After la limitation, consultez Réduire les erreurs de limitation.

Informations de diagnostic

Tous les contenus de la réponse qui ne sont pas utilisés dans les étapes précédentes sont destinés à diagnostics uniquement (y compris les chaînes dans les champs de message). Nous vous déconseillons de dépendre de ces contenus, car ils peuvent changer sans préavis.

Gestion des cas spéciaux

Pour les demandes de session, si vous rencontrez une 502/badGateway erreur ou 503/serviceUnavailable , lorsqu’un code d’erreur de deuxième niveau connu est trouvé, suivez les instructions correspondantes ; sinon, vous devez recréer la session directement.

Contenu connexe

• Travailler avec Excel dans Microsoft Graph