Gestion des erreurs

L'API utilise des codes de réponse HTTP conventionnels pour indiquer le succès ou l'échec des requêtes. Cette page documente les formats d'erreur et les stratégies de gestion.

Codes d'état HTTP

Codes de succès

Code	Description
200	La requête a réussi. Le corps de la réponse contient les données demandées.
201	Ressource créée avec succès.

Codes d'erreur

Code	Description
400	Mauvaise Requête - Paramètres invalides ou corps de requête mal formé
401	Non autorisé - Clé d'API manquante ou invalide
403	Interdit - La clé d'API n'a pas les permissions requises
404	Non trouvé - La ressource demandée n'existe pas
429	Trop de requêtes - Limite de débit dépassée
500	Erreur interne du serveur - Veuillez contacter le support si le problème persiste

Format de réponse d'erreur

Toutes les réponses d'erreur suivent une structure JSON cohérente avec un objet d'erreur contenant les champs code, message et détails.

Error Response Structurejson

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key",
    "details": "The X-API-Key header is required for authentication"
  }
}

Scénarios d'erreur courants

401

Clé API invalide

Cette erreur se produit lorsque la clé API est manquante, invalide ou a été révoquée. Vérifiez que vous incluez l'en-tête X-API-Key avec une clé valide.

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key",
    "details": "The provided API key is invalid or has been revoked"
  }
}

403

Permissions insuffisantes

Cette erreur se produit lorsque votre clé d'API ne dispose pas des autorisations requises pour le point de terminaison demandé. Contactez votre administrateur pour mettre à jour les autorisations de la clé.

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions",
    "details": "This API key does not have the DEVICES_READ permission"
  }
}

429

Limité par le taux

Cette erreur se produit lorsque vous avez dépassé la limite de taux. La réponse inclut des informations sur le moment où vous pouvez réessayer.

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests",
    "details": "Rate limit exceeded. Try again in 45 seconds"
  }
}

Meilleures pratiques de gestion des erreurs

Implémentez une gestion des erreurs robuste dans votre intégration pour gérer gracieusement les échecs et réessayer automatiquement les erreurs transitoires.

Error Handling Example

import requests
import time

API_KEY = "nm_acme_abc123..."
BASE_URL = "https://api.nomid.tech/emm/api/v1"

def make_request(endpoint, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(
            f"{BASE_URL}{endpoint}",
            headers={"X-API-Key": API_KEY}
        )
        
        if response.status_code == 200:
            return response.json()
        
        if response.status_code == 401:
            raise Exception("Invalid API key")
        
        if response.status_code == 403:
            raise Exception("Insufficient permissions")
        
        if response.status_code == 429:
            # Get retry time from header or use default
            retry_after = int(response.headers.get("X-RateLimit-Reset", 60))
            wait_time = min(retry_after, 60)
            print(f"Rate limited. Waiting {wait_time}s...")
            time.sleep(wait_time)
            continue
        
        if response.status_code >= 500:
            # Exponential backoff for server errors
            wait_time = (2 ** attempt) * 1
            print(f"Server error. Retrying in {wait_time}s...")
            time.sleep(wait_time)
            continue
        
        # Unknown error
        response.raise_for_status()
    
    raise Exception(f"Failed after {max_retries} retries")

Stratégie de nouvelle tentative

Pour les erreurs transitoires, implémentez une stratégie de nouvelle tentative avec une backoff exponentielle :

Pour les erreurs 429, attendez le temps spécifié dans l'en-tête X-RateLimit-Reset avant de réessayer
Pour les erreurs 5xx, utilisez une backoff exponentielle (1s, 2s, 4s, 8s...) avec jitter
Définissez un nombre maximum de nouvelles tentatives (par exemple, 3 à 5 tentatives) pour éviter les boucles infinies

Codes d'état HTTP

Codes de succès

Code	Description
200	La requête a réussi. Le corps de la réponse contient les données demandées.
201	Ressource créée avec succès.

Codes d'erreur

Code	Description
400	Mauvaise Requête - Paramètres invalides ou corps de requête mal formé
401	Non autorisé - Clé d'API manquante ou invalide
403	Interdit - La clé d'API n'a pas les permissions requises
404	Non trouvé - La ressource demandée n'existe pas
429	Trop de requêtes - Limite de débit dépassée
500	Erreur interne du serveur - Veuillez contacter le support si le problème persiste

Format de réponse d'erreur

Toutes les réponses d'erreur suivent une structure JSON cohérente avec un objet d'erreur contenant les champs code, message et détails.

Error Response Structurejson

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key",
    "details": "The X-API-Key header is required for authentication"
  }
}

Scénarios d'erreur courants

401

Clé API invalide

Cette erreur se produit lorsque la clé API est manquante, invalide ou a été révoquée. Vérifiez que vous incluez l'en-tête X-API-Key avec une clé valide.

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key",
    "details": "The provided API key is invalid or has been revoked"
  }
}

403

Permissions insuffisantes

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions",
    "details": "This API key does not have the DEVICES_READ permission"
  }
}

429

Limité par le taux

Cette erreur se produit lorsque vous avez dépassé la limite de taux. La réponse inclut des informations sur le moment où vous pouvez réessayer.

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests",
    "details": "Rate limit exceeded. Try again in 45 seconds"
  }
}

Meilleures pratiques de gestion des erreurs

Implémentez une gestion des erreurs robuste dans votre intégration pour gérer gracieusement les échecs et réessayer automatiquement les erreurs transitoires.

Error Handling Example

import requests
import time

API_KEY = "nm_acme_abc123..."
BASE_URL = "https://api.nomid.tech/emm/api/v1"

def make_request(endpoint, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(
            f"{BASE_URL}{endpoint}",
            headers={"X-API-Key": API_KEY}
        )
        
        if response.status_code == 200:
            return response.json()
        
        if response.status_code == 401:
            raise Exception("Invalid API key")
        
        if response.status_code == 403:
            raise Exception("Insufficient permissions")
        
        if response.status_code == 429:
            # Get retry time from header or use default
            retry_after = int(response.headers.get("X-RateLimit-Reset", 60))
            wait_time = min(retry_after, 60)
            print(f"Rate limited. Waiting {wait_time}s...")
            time.sleep(wait_time)
            continue
        
        if response.status_code >= 500:
            # Exponential backoff for server errors
            wait_time = (2 ** attempt) * 1
            print(f"Server error. Retrying in {wait_time}s...")
            time.sleep(wait_time)
            continue
        
        # Unknown error
        response.raise_for_status()
    
    raise Exception(f"Failed after {max_retries} retries")

Stratégie de nouvelle tentative

Pour les erreurs transitoires, implémentez une stratégie de nouvelle tentative avec une backoff exponentielle :

Pour les erreurs 429, attendez le temps spécifié dans l'en-tête X-RateLimit-Reset avant de réessayer

Pour les erreurs 5xx, utilisez une backoff exponentielle (1s, 2s, 4s, 8s...) avec jitter

Définissez un nombre maximum de nouvelles tentatives (par exemple, 3 à 5 tentatives) pour éviter les boucles infinies