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/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
| HTTP | Code | Message et cas | type |
|---|---|---|---|
| 400 | NX-API-001 | Les 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. |
|
| 401 | NX-AUT-010 | Clé 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. |
|
| 403 | NX-ACC-002 | Vous 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. |
|
| 404 | NX-API-002 | Cet élément est introuvable. Appareil inconnu ou non rattaché au propriétaire de la clé : les deux cas donnent la même réponse. |
|
| 409 | NX-API-003 | Cette opération entre en conflit avec des données existantes. L’appareil est hors ligne : la commande n’a pas pu lui être transmise. |
|
| 429 | NX-API-005 | Trop 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. |
|
| 500 | NX-API-004 | Un 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. | |
| 503 | NX-NET-002 | Le service est momentanément injoignable. Réessayez dans un instant. Un service nécessaire est momentanément indisponible. Réessayez plus tard. |
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 limitesGestion des clés
Réponses des routes de clés utilisées par la console, au format d’erreur commun.
| HTTP | Code | Message et cas |
|---|---|---|
| 400 | NX-API-001 | Les informations envoyées sont incomplètes ou invalides. Nom vide ou trop long, scope inconnu, durée hors bornes, corps illisible. |
| 401 | NX-AUT-003 | Votre session a expiré. Reconnectez-vous. Pas de session, ou session expirée : reconnectez-vous. |
| 403 | NX-AUT-008 | La 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. |
| 404 | NX-API-002 | Cet élément est introuvable. Clé inconnue ou clé d’un autre compte : même réponse. |
| 409 | NX-API-003 | Cette opération entre en conflit avec des données existantes. Nombre de clés permis par le plan atteint. |
| 500 | NX-API-004 | Un problème est survenu de notre côté. Réessayez dans un instant. Panne interne. |