Contrat des réponses et des erreurs de l’API d’administration

Ce fichier complète le contrat de réponse de chaque point de terminaison de Référence des points de terminaison. Consultez la ligne du point de terminaison pour le corps de réussite et les tableaux ci-dessous pour chaque corps d’échec commun ou spécifique. Par défaut, les erreurs utilisent plusieurs structures de compatibilité ; les appelants peuvent choisir une enveloppe universelle.

Enveloppe d’erreur structurée facultative

Envoyez cet en-tête de requête sur n’importe quel point de terminaison :

X-Error-Format: envelope

La comparaison de valeur ignore les espaces en début et en fin et ne tient pas compte de la casse. Avec cette valeur exacte, toute réponse JSON dont le statut est 400 ou supérieur est convertie en :

ErrorEnvelope = {
  error: {
    code: string,
    message: string,
    details: Record<string, unknown>,
    requestId: string
  }
}

Exemple de conversion d’un corps de validation par défaut :

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Invalid request",
    "details": {
      "fields": {
        "name": ["String must contain at least 1 character(s)"]
      }
    },
    "requestId": "integration-42"
  }
}

Les règles de conversion sont précises :

• validationErrors devient details.fields, et code devient VALIDATION_FAILED, même si le corps par défaut avait aussi un code métier.
• La valeur code par défaut au premier niveau est conservée en l’absence de champs de validation.
• Les autres propriétés de premier niveau, à l’exception de error, message, validationErrors et code, sont déplacées dans details ; par exemple, limit d’un export de rapport devient details.limit.
• Un champ error de type chaîne au premier niveau devient message. S’il n’existe pas, le message de repli associé au statut est utilisé.
• Les codes de repli sont AUTH_REQUIRED (401), PERMISSION_DENIED (403), RESOURCE_NOT_FOUND (404), CONFLICT (409), VALIDATION_FAILED (422 et autres 4xx non classés), RATE_LIMITED (429), EXTERNAL_PROVIDER_FAILED (502) et INTERNAL_ERROR (autres 5xx, y compris 503).
• requestId est l’en-tête de réponse X-Request-Id exact. Un ID de requête fourni par l’appelant n’est utilisé que s’il correspond à [A-Za-z0-9._:-]{1,128} après suppression des espaces de début et de fin ; sinon, le serveur génère un UUID.

Cette transformation ne change ni le statut ni les en-têtes non liés au corps. Elle s’applique aussi aux répétitions idempotentes selon l’en-tête X-Error-Format de la requête de répétition. Les réponses binaires de réussite restent binaires ; leurs erreurs JSON sont enveloppées. Les tableaux restants montrent les corps par défaut ; appliquer les règles ci-dessus donne l’autre corps de réponse possible pour chaque ligne.

Notation des réponses

ValidationError = {
  validationErrors: Record<string, string[]>,
  code?: string
}

CodedError = {
  error: string,
  code: string,
  // a route may add fields explicitly listed below
}

PlainError = { error: string }

error et le texte des messages de validation sont descriptifs, pas des discriminants programmatiques stables. Fondez les branchements sur code lorsqu’il est présent. La validation de requête renvoie 422 ValidationError ; la validation d’un objet entier peut produire { "validationErrors": {} } lorsqu’aucun champ individuel n’est identifié. Le JSON invalide et les erreurs inattendues renvoient le 500 PlainError global ci-dessous.

Tous les exemples JSON montrent la structure exacte du corps. Le texte représenté par <message> est le message de validation ou d’opération renvoyé : il s’agit d’une chaîne JSON, pas d’une valeur littérale entre chevrons.

Ordre de traitement des requêtes

Les requêtes sont traitées dans cet ordre :

1. la configuration et l’authentification des jetons d’espace de travail ;
2. la politique de l’hôte et les limites de fréquence du jeton/de l’espace de travail ;
3. le filtrage des droits actuels ;
4. pour chaque mutation, validation et réservation de la clé d’idempotence ;
5. les contrôles de portées du point de terminaison, la validation de la requête et l’opération demandée.

Une mutation avec un jeton valide mais aux portées insuffisantes doit donc quand même envoyer Idempotency-Key. Une réponse terminée à une mutation 403, 404, 409 ou 422 peut être répétée pour la même clé et la même requête.

Réponses d’authentification, de politique et de limitation des requêtes

Ces réponses peuvent survenir sur chaque point de terminaison /v2/admin enregistré avant son traitement spécifique.

L’accès à l’API est inclus dans toutes les offres. Désactiver le paramètre adminApiEnabled de l’hôte de l’espace de travail renvoie 404 ; perdre un droit supplémentaire à une fonctionnalité retire uniquement les portées concernées. Le refus de portée qui en résulte utilise la réponse ci-dessous, et non un mécanisme de renouvellement du jeton.

Erreurs de portée, d’idempotence, d’analyse, d’appartenance et erreurs inattendues

Les ID de ressources dans le chemin doivent être des nombres positifs. Un :siteId, :chargerId, :portId, :tariffId, :profileId, :assignmentId, :userId, :rfidId, :accessId, :limitId ou :localUserId non positif ou non numérique renvoie 422 ValidationError, et non 400.

Erreurs des sites et de gestion de la puissance

Erreurs des bornes

mapChargerErrors() est utilisé pour la création/mise à jour des bornes, les identifiants, les paramètres de connecteur, la publication publique, la résolution des données QR, la modification/le rechargement de configuration, le lancement du micrologiciel, les quatre commandes de base et la demande de programmation composite.

Les simples lectures renvoient uniquement les réponses communes 401/403/404/429/500/503, ainsi que 422 pour la validation des paramètres ou du chemin. La suppression d’une borne peut renvoyer le 500 PlainError commun si elle échoue sans réponse d’erreur plus précise.

Erreurs des rapports

L’export réussi est binaire ; toutes les erreurs d’export restent en JSON.

Erreurs des tarifs

Erreurs des profils de recharge

Erreurs métier des utilisateurs

Les erreurs de validation utilisateur qui identifient un champ utilisent ValidationError et code ; les autres erreurs utilisateur utilisent CodedError. Tous les cas de ressources absentes utilisent la réponse commune RESOURCE_NOT_FOUND, qui ne révèle pas l’existence des ressources.

POST /users/invitations peut aussi renvoyer le 403 INSUFFICIENT_SCOPE commun après analyse du corps si users:access est absent, ou si un RFID a été fourni et que users:rfid est absent. Les points de terminaison d’utilisateur local répertorient chaque portée requise dans Référence des points de terminaison.

Les codes d’erreur utilisateur s’appliquent comme suit :

Tous les résultats liés à l’appartenance et aux ressources absentes dans ces familles, y compris un e-mail non enregistré sur POST /users, utilisent le corps commun 404 RESOURCE_NOT_FOUND.

Réponses sans corps et réponses répétées

Une réponse 204 réussie n’a pas de corps. Cela vaut pour toute suppression documentée mentionnant 204 empty. Une répétition idempotente terminée définit Idempotency-Replayed: true et utilise le statut et le corps enregistrés ; pour 204, la réponse HTTP reste sans corps. L’API ne renvoie jamais d’objet JSON de réussite pour une opération 204 documentée.