API publique

Erreurs

Toute erreur de l’API publique répond au format application/problem+json. Le champ code reprend le catalogue commun de Nexus System ; le champ type précise la sorte d’erreur. Votre code doit se fier à code et type, jamais au texte.

Format d’une réponse d’erreur

  • code — code Nexus System, stable : c’est lui qu’il faut tester.
  • type — adresse qui nomme la sorte précise d’erreur (son dernier segment figure dans le tableau ci-dessous).
  • detail — explication pour vous, en anglais ; elle peut changer, ne la montrez pas telle quelle à vos utilisateurs.
  • request_id — identifiant de la requête, identique à l’en-tête X-Request-Id : à donner à l’assistance pour retrouver l’appel.
http
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
X-Request-Id: 01JC8Q3Z6X5V2M4N7P9R0S1T2U

{
  "type": "https://api.nexus-system.fr/errors/unknown-metric",
  "title": "Unknown metric",
  "status": 400,
  "code": "NX-API-001",
  "detail": "metric \"salinity\" is not described for this device type",
  "request_id": "01JC8Q3Z6X5V2M4N7P9R0S1T2U"
}

Codes de l’API publique

HTTPCodeMessage et castype
400NX-API-001Les informations envoyées sont incomplètes ou invalides.

Paramètre ou valeur invalide : mesure inconnue, période trop longue, réglage inconnu ou hors bornes, commande inconnue.

  • bad-request
  • unknown-metric
  • period-too-long
  • unknown-setting
  • invalid-setting
  • unknown-command
401NX-AUT-010Clé d’API absente, invalide, expirée ou révoquée.

En-tête Authorization absent, ou clé inconnue, suspendue, expirée ou révoquée.

  • invalid-api-key
403NX-ACC-002Vous n’avez pas les droits nécessaires pour cette action.

La clé n’a pas le scope demandé, ou le plan du compte ne permet pas l’écriture, cet appareil ou cette période.

  • missing-scope
  • plan-write-forbidden
  • plan-device-limit
  • plan-history-limit
404NX-API-002Cet élément est introuvable.

Appareil inconnu ou non rattaché au propriétaire de la clé : les deux cas donnent la même réponse.

  • device-not-found
  • not-found
409NX-API-003Cette opération entre en conflit avec des données existantes.

L’appareil est hors ligne : la commande n’a pas pu lui être transmise.

  • device-offline
429NX-API-005Trop de requêtes. Patientez avant de réessayer.

Quota du compte ou limite de l’adresse IP atteint. Attendez le nombre de secondes indiqué par Retry-After.

  • rate-limited
500NX-API-004Un problème est survenu de notre côté. Réessayez dans un instant.

Panne interne. Réessayez plus tard ; si elle persiste, signalez-la avec le request_id.

    503NX-NET-002Le service est momentanément injoignable. Réessayez dans un instant.

    Un service nécessaire est momentanément indisponible. Réessayez plus tard.

    • upstream-unavailable

    Quand réessayer

    Réessayez seulement après un 429 (au bout de Retry-After secondes), un 503 ou un 500, en espaçant les essais. Un 400, 401, 403 ou 404 ne changera pas tant que la requête, la clé ou le plan ne changent pas. Chaque réponse porte les en-têtes RateLimit-Limit, RateLimit-Remaining et RateLimit-Reset.

    Plans et limites

    Gestion des clés

    Réponses des routes de clés utilisées par la console, au format d’erreur commun.

    HTTPCodeMessage et cas
    400NX-API-001Les informations envoyées sont incomplètes ou invalides.

    Nom vide ou trop long, scope inconnu, durée hors bornes, corps illisible.

    401NX-AUT-003Votre session a expiré. Reconnectez-vous.

    Pas de session, ou session expirée : reconnectez-vous.

    403NX-AUT-008La création de clés d’API est réservée aux comptes disposant de l’accès développeur.

    Le compte n’a pas l’accès développeur.

    404NX-API-002Cet élément est introuvable.

    Clé inconnue ou clé d’un autre compte : même réponse.

    409NX-API-003Cette opération entre en conflit avec des données existantes.

    Nombre de clés permis par le plan atteint.

    500NX-API-004Un problème est survenu de notre côté. Réessayez dans un instant.

    Panne interne.