Codes de réponse de l’API de référence

S’applique à : Espace partenaires | Références de l’Espace partenaires

Rôles appropriés : administrateur de Références | utilisateur de Références

Les API REST Références de l’Espace partenaires retournent un objet JSON qui contient un code d’état. Ce code qui indique si votre demande a réussi ou pourquoi elle a échoué.

Réponses réussies

Un code d’état 2xx indique que la demande du client a été reçue, comprise et acceptée. Les codes d’état 2xx suivants indiquent une réponse de réussite :

• 200 : Réussite confirmée
• 201 : Ressource créée
• 202 : Accepté
• 204 : Aucun contenu à retourner

Réponses d’erreur

Toute réponse avec un code d’état 4xx ou 5xx inclut un message d’erreur contenant des détails sur les conditions d’erreur de ce code.

Le tableau suivant répertorie et décrit les codes d’état HTTP qui peuvent être retournés pour les scénarios d’erreur.

Code d’état	Message d’état	Description
400	Demande incorrecte	Impossible de traiter la demande, car elle est incorrecte ou incorrecte.
401	Non autorisé	Les informations d’authentification requises sont manquantes ou non valides pour la ressource.
403	Interdit	L’accès est refusé à la ressource demandée. L’utilisateur n’a peut-être pas les autorisations suffisantes.
404	Introuvable	La ressource demandée n’existe pas.
405	Méthode non autorisée	La méthode HTTP dans la requête n’est pas autorisée sur la ressource.
406	Non acceptable	Ce service ne prend pas en charge le format demandé dans l’en-tête Accept.
409	Conflit	L’état actuel est en conflit avec ce que la demande attend. Par exemple, le dossier parent spécifié n’existe peut-être pas.
410	Supprimé	La ressource demandée n'est plus disponible sur le serveur.
411	Longueur requise	Un en-tête Content-Length est requis sur la demande.
412	Échec de la précondition	Une condition préalable fournie dans la requête (par exemple, un en-tête if-match) ne correspond pas à l’état actuel de la ressource.
413	Entité de requête trop grande	La taille de la demande dépasse la limite maximale.
415	Type de média non pris en charge	Le type de contenu de la requête est un format que le service ne prend pas en charge.
416	Plage demandée non satisfaisante	La plage d’octets spécifiée n’est pas valide ou n’est pas disponible.
422	Impossible de traiter l’entité	Impossible de traiter la demande, car elle est sémantiquement incorrecte.
423	Verrouillé	La ressource faisant l’objet d’un accès est verrouillée.
429	Trop de demandes	L’application cliente est limitée et ne doit pas tenter de répéter la demande pendant un certain temps.
500	Erreur interne du serveur	Une erreur interne de serveur s’est produite lors du traitement de la demande.
501	Non implémentée	La fonctionnalité demandée n’est pas implémentée.
503	Service indisponible	Le service est temporairement indisponible à des fins de maintenance ou est surchargé. Vous pouvez répéter la demande après un certain délai, dont la longueur peut être spécifiée dans un en-tête Retry-After.
504	Délai d’expiration de passerelle	Le serveur, agissant en tant que proxy, n’a pas reçu de réponse en temps opportun du serveur en amont qu’il avait besoin d’accéder lors de la tentative d’exécution de la requête. Peut se produire avec l’erreur 503.
507	Stockage insuffisant	Atteint le quota de stockage maximal.
509	Limite de bande passante dépassée	Application cliente limitée pour dépasser la limite de bande passante maximale. Votre application peut réessayer la requête après un certain temps.

Type de ressource d’erreur

La réponse d’erreur est un objet JSON unique qui contient une propriété unique nommée error. Cet objet contient tous les détails de l’erreur. Vous pouvez utiliser les informations retournées ici au lieu, ou en plus, du code d’état HTTP.

Le tableau et les exemples de code suivants décrivent le schéma d’une réponse d’erreur.

Nom	Type	Description
code	string	Toujours retourné. Indique le type d’erreur qui s’est produit. Non Null.
message	string	Toujours retourné. Décrit l’erreur en détail et fournit des informations de débogage supplémentaires. Non null nonempty. La longueur maximale est de 1 024 caractères.
innerError	object	facultatif. Un autre objet d’erreur avec des informations plus spécifiques concernant l’erreur s’est produite.
innerError.code	chaîne numérique	Toujours retourné, si innerError n’est pas null. Fournit des informations de code d’erreur plus spécifiques sous la valeur du code d’erreur supérieure.
innerError.message	string	Toujours retourné, si innerError n’est pas null. Fournit un message d’erreur plus spécifique sous la chaîne de message d’erreur supérieure.
innerError.details	tableauobjet	facultatif. Contient plus de détails sur l’erreur. Principalement utile dans les erreurs de validation d’entrée.
cible	string	facultatif. Cible d’origine de l’erreur.

Exemple de réponse d’erreur

{
  "error": {
    "code": "unauthenticated",
    "message": "The caller is not authenticated.",
    "innerError": {
      "code": "99902",
      "message": "Request not authenticated",
      "details": null
    }
  }
}

Un autre exemple avec l’objet innerError.details rempli :

{
  "error": {
    "code": "invalidRequest",
    "message": "The request is malformed or incorrect.",
    "innerError": {
      "code": "99901",
      "message": "InvalidInput",
      "details": [
        {
          "InvalidReferralForCoSellConversion": [
            "If PartnerLed referral has no solution it cannot be converted to co-sell referral"
          ]
        }
      ]
    }
  }
}

Propriété code

La propriété code contient l’une des valeurs possibles suivantes. Vos applications doivent être prête à gérer chacune de ces erreurs.

Code	Code d’état Http	Description
invalidRequest	400	La demande est mal exprimée ou incorrecte.
unauthenticated	401	L’appelant n’est pas authentifié.
accessDenied	403	L’appelant n’est pas autorisé à effectuer l’action.
itemNotFound	404	Impossible de trouver la ressource.
resourceModified	409	La ressource en cours de mise à jour a été modifiée depuis la dernière lecture de l’appelant, généralement une incompatibilité eTag.
preconditionFailed	412	Une condition préalable fournie dans la requête (par exemple, un en-tête if-match) ne correspond pas à l’état actuel de la ressource.
generalException	500	Une erreur non spécifiée s'est produite.
serviceNotAvailable	503	Le service n’est pas disponible. Renouvelez la demande après un certain délai. Il peut y avoir un en-tête Retry-After.

Propriété message

La propriété message à la racine contient un message d’erreur destiné à être lu par le développeur. Les messages d’erreur ne sont pas localisés et ne doivent pas être affichés directement à l’utilisateur. Votre code ne doit pas vérifier les message valeurs uniquement parce qu’elles peuvent changer à tout moment, et elles contiennent souvent des informations dynamiques spécifiques à la demande ayant échoué. Vous devez coder par rapport aux codes d’erreur retournés dans les code propriétés, puis pour plus d’informations, combinez-le avec du texte du message.

Objet InnerError

L’objet innererror peut contenir de manière récursive davantage innererror d’objets avec des codes d’erreur plus spécifiques. L’application cliente, lors de la gestion d’une erreur, doit parcourir tous les codes d’erreur disponibles et utiliser le code d’erreur le plus détaillé qu’ils comprennent.

Il existe d’autres erreurs que votre application peut rencontrer dans les objets imbriqués innererror . Les applications ne sont pas requises pour gérer ces erreurs, mais peuvent le faire s’ils le choisissent. Le service peut ajouter de nouveaux codes d’erreur ou arrêter de retourner des anciens à tout moment. Il est donc important que toutes les applications puissent gérer les [codes d’erreur de base].

Codes d’erreur

Voici les codes d’erreur retournés par les API :

État HTTP	Code d’erreur HTTP	Code d'erreur	Description
BadRequest	400	99901	entrée non valide
Non autorisé	401	99902	Accès non autorisé
BadRequest	400	99903	Entrée manquante
NotFound	404	99,904	Ressource introuvable
InternalServerError	500	99905	Erreur non spécifiée
TooManyRequests	429	99906	Trop de demandes
InternalServerError	500	99907	Erreur interne temporaire
BadRequest	400	99908	La propriété n’est pas modifiable
BadRequest	400	99909	La propriété n’est pas nullable
Échec de la condition préalable	412	99910	La valeur Etag ne correspond pas
BadRequest	400	99911	État de référence non valide à inviter
BadRequest	400	99912	La solution avec le type 'name' est requise
Interdit	403	99913	Organisation non autorisée à créer une ressource
Interdit	403	99914	Organisation non autorisée à participer à des engagements de co-vente
InternalServerError	500	99915	Échec d’exécution de requête interne
Conflit	409	99917	Ressource déjà modifiée via une autre requête
PreConditionFailed	412	99918	Une condition préalable fournie dans la requête (par exemple, un en-tête if-match) ne correspond pas à l’état actuel de la ressource.
BadRequest	400	99919	Qualification de référence non valide pour la mise à jour
InternalServerError	500	99999	Exception générale lors du traitement de la demande