Erreurs

Lorsqu'une requête échoue, WEEGLOO renvoie un corps d'erreur au format uniforme accompagné d'un code de statut HTTP. La forme du corps de réponse est la même quelle que soit l'API (CMA, CDA, ACMA, ACDA, Upload, Auth) sur laquelle l'échec s'est produit. Ainsi, dès que vous savez traiter un seul format, vous pouvez aiguiller toutes les erreurs de la même manière. Cette page rassemble en un seul endroit ce format commun et les codes d'erreur les plus fréquents.

Format de la réponse d'erreur

Le corps d'erreur se présente sous la forme suivante. Ci-dessous, la réponse reçue lors de la consultation d'un WebHosting inexistant.

{
  "requestId": "GeR3sEbvWdgvv9eW2NXeanpj2wo6qbkVXgIW7Qd3ea6",
  "sys": {
    "id": "RxcgyPTSuk4GDy6s",
    "type": "NotFound",
    "code": "WGL404001",
    "timestamp": 1781785683556
  },
  "details": {
    "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } }
  },
  "reason": "WebHosting(...) has been deleted or does not exist.",
  "suggestion": "Please verify WebHosting and try again."
}

La signification de chaque clé est la suivante.

CléTypeDescription
requestIdstringIdentifiant de suivi de cette requête. Transmettez cette valeur lorsque vous contactez le support pour qu'il retrouve rapidement la requête concernée.
sys.typestringCatégorie de l'erreur. Indique une grande famille telle que Unauthorized, Forbidden, NotFound, Unprocessable, Conflict ou TooManyRequest.
sys.codestringCode d'erreur détaillé (par exemple WGL409005). Employez cette valeur pour aiguiller au niveau du code.
sys.timestampintegerInstant de survenue de l'erreur (epoch millis).
reasonstringCause de l'échec, lisible par un humain.
suggestionstringIndice pour aider à la résolution.
detailsobject (facultatif)Informations complémentaires. Y figurent un Refer désignant la ressource concernée, la liste des éléments en erreur de validation (errors), etc. Peut être absent selon le genre d'erreur.

L'aiguillage se fait selon l'unité dont vous avez besoin, sys.type (grande famille) ou sys.code (code détaillé). Pour un même sys.type, un sys.code différent correspond à une cause différente ; si un traitement précis est nécessaire, fondez-vous sur sys.code.

En cas d'échec de validation, details.errors contient les éléments en infraction. Voici la réponse obtenue en plaçant dans le corps une propriété absente du schéma, ce qui fait échouer la validation.

{
  "requestId": "yJ8KpQ2mWtnLrZ4Xv7BcEadfh3sNuMvKbGT5Pq9wRsx",
  "sys": {
    "id": "Lm2Nq9Tr8KdW4xZc",
    "type": "BadRequest",
    "code": "WGL400006",
    "timestamp": 1781776000000
  },
  "details": {
    "errors": [
      { "path": "", "message": "property 'X' is not defined in the schema", "property": "X" }
    ]
  },
  "reason": "Some values do not satisfy validation rules.",
  "suggestion": "Please check the request body and try again."
}

Chaque élément de details.errors contient l'emplacement en infraction (path), une explication (message) et le nom de la propriété concernée (property). S'il y a plusieurs éléments, il y en a un par valeur en infraction.

Codes fréquents

Voici les codes d'erreur que l'on rencontre souvent.

CodeCatégorieSignificationSituation courante
WGL401001UnauthorizedLe jeton n'est pas valideLe jeton Bearer de l'en-tête Authorization a expiré ou est incorrect.
WGL403001ForbiddenPermission manquanteLe rôle de l'appelant n'autorise pas cette opération. Une requête bloquée à cause du point d'appel, et non du rôle, revient avec le WEB403001 ci-dessous.
WEB403001ForbiddenAucun droit d'accès à la ressourceLa requête elle-même n'est pas autorisée et a donc été refusée. Lors d'un appel avec un Delivery Access Token ou un Space Access Token, une requête arrêtée par le contrôle de allowedReferrers revient avec ce code. C'est un code différent de WGL403001, qui signifie que le rôle ne possède pas la permission.
WGL403012ForbiddenFonctionnalité suspendue pour dépassement d'usageLa consommation de trafic ou d'espace de stockage de l'Organization a dépassé le volume inclus dans le forfait, ce qui a suspendu la fonctionnalité concernée (par exemple, les API de lecture, l'envoi de nouveaux Media, le déploiement de Web Hosting). Contrairement à WGL429001, qui porte sur une limite de nombre, il s'agit ici d'une suspension pour dépassement d'usage. Pour les conditions de levée, consultez Forfaits.
WGL404001NotFoundLa ressource est absente ou suppriméeConsultation avec un sys.id incorrect, ou appel d'une fonctionnalité pas encore configurée (par exemple, domaine personnalisé non rattaché).
WGL400006BadRequestLa valeur du corps enfreint les règles de validationLe corps a été envoyé avec une clé de champ ou un type incorrect. Les éléments en infraction figurent dans details.errors.
WEB400014BadRequestUn champ de tri est absent de selectLe champ utilisé dans order n'a pas été placé dans select. Tous les champs utilisés pour le tri doivent aussi figurer dans select (voir Paramètres de requête communs).
WGL409005ConflictLa ressource a été modifiée entre-tempsL'en-tête X-Weegloo-Version est absent ou diffère de la version actuelle (voir Conventions).
WGL422007UnprocessableImpossible d'archiver car l'élément est publiéPour archiver un Content ou un Media, il faut d'abord le dépublier.
WGL422009UnprocessableImpossible de supprimer car l'élément est publiéPour supprimer un Content ou un Media publié, il faut d'abord le dépublier.
WGL429001TooManyRequestLimite du forfait dépasséeLe nombre de ressources créées, comme Organization ou Space, dépasse la limite du forfait actuel. Passer à un forfait supérieur relève la limite.

Les codes ci-dessus ne sont qu'une partie des plus fréquents. Selon l'opération et la ressource, il peut en exister bien d'autres. Quel que soit le code reçu, identifiez la grande famille avec sys.type, puis vérifiez la cause précise et la piste de résolution avec reason et suggestion.

  • Conventions : la règle de concurrence X-Weegloo-Version pour éviter WGL409005.
  • Propriétés système (sys) : l'état de publication (status) et le cycle de vie désigné par WGL422007 et WGL422009.
  • Forfaits : les seuils par forfait de WGL403012 (suspension pour dépassement d'usage) et de WGL429001 (limite de nombre), et la manière de les lever.