Gestion d'Erreurs

Référence complète des codes d'erreur et réponses de l'API Sharokey lors de l'utilisation de nos SDK officiels.

📋 Aperçu

Nos SDK gèrent automatiquement tous les scénarios d'erreur et fournissent des objets d'erreur structurés. Cette référence montre les formats d'erreur que vous recevrez et comment les gérer efficacement.

SDK Officiels :

• Outil CLI C# - Interface en ligne de commande multiplateforme
• JavaScript SDK - Pour Node.js et les applications web modernes
• JavaScript CDN - Intégration navigateur simple
• Python SDK - Client Python asynchrone

🔴 Format de Réponse d'Erreur

Toutes les erreurs API suivent une structure JSON cohérente que nos SDK analysent automatiquement :

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Description d'erreur lisible par l'humain",
    "details": {
      "field": "nom_du_champ",
      "value": "valeur_invalide",
      "additional_context": "Plus d'informations"
    }
  },
  "timestamp": "2025-01-14T10:30:00Z",
  "request_id": "req_abcd1234efgh5678"
}

🚨 Erreurs d'Authentification

Token Invalide

{
  "success": false,
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "message": "Token invalide ou expiré"
  }
}

Causes Communes :

• Token non configuré dans le SDK
• Token malformé ou corrompu
• Token a expiré

Gestion SDK : Tous les SDK détectent les erreurs d'authentification et fournissent un feedback clair sur les problèmes de token.

Permissions Insuffisantes

{
  "success": false,
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "Permissions insuffisantes pour cette opération",
    "details": {
      "required_scope": "secrets:create",
      "token_scopes": ["secrets:read", "stats:read"]
    }
  }
}

Solution : Utilisez un token avec les portées appropriées pour vos opérations.

⚠️ Erreurs de Validation

Validation du Contenu

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Le champ content est requis",
    "details": {
      "content": ["Le champ content est requis"],
      "expiration": ["Doit être entre 1 et 1000 heures"]
    }
  }
}

Problèmes de Validation Courants :

• content : Le contenu du secret ne peut pas être vide
• hours : Doit être entre 1 et 1000
• maximum_views : Doit être entre 1 et 10
• description : Maximum 255 caractères
• password : Minimum 4 caractères si fourni

Erreurs de Pièces Jointes

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "La taille totale des pièces jointes doit être inférieure à 10MB"
  }
}

Limites de Fichiers :

• Maximum de pièces jointes : 10 fichiers par secret
• Limite de taille totale : 10MB par secret
• Extensions supportées : pdf, jpg, jpeg, png, docx, txt

🔍 Erreurs de Ressource

Secret Non Trouvé

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Secret non trouvé ou expiré"
  }
}

Causes Communes :

• Secret a été supprimé
• Secret a expiré naturellement
• Mauvais slug fourni
• Aucune permission pour accéder au secret

🚦 Erreurs de Limitation de Taux

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Trop de requêtes. Veuillez réessayer plus tard."
  }
}

Limites de Taux :

• Authentification : 10 requêtes par minute
• Opérations secrets : 30 requêtes par minute
• Requêtes de tokens d'entreprise : 5 requêtes par minute

Gestion SDK : Tous les SDK implémentent une logique de nouvelle tentative automatique avec backoff exponentiel.

💰 Erreurs de Quota

{
  "success": false,
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Vous avez atteint le nombre maximum de secrets autorisés pour votre plan actuel."
  }
}

Solution : Améliorez votre plan ou attendez la réinitialisation du quota.

🖥️ Erreurs Serveur

Erreur Serveur Interne

{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Une erreur serveur interne s'est produite",
    "details": {
      "error_id": "err_abcd1234",
      "support_message": "Veuillez contacter le support avec cet ID d'erreur"
    }
  }
}

Service Indisponible

{
  "success": false,
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Service temporairement indisponible",
    "details": {
      "retry_after": 300,
      "maintenance_window": false
    }
  }
}

🛠️ Gestion d'Erreurs SDK

Gestion d'Erreurs CLI C#

# Le CLI fournit des messages d'erreur clairs et des codes de sortie
sharokey create "content" --hours 25000
# Erreur : Les heures doivent être entre 1 et 1000 (code de sortie 1)

# Sortie JSON pour les scripts
sharokey create "content" --hours 25000 --json
# {"success": false, "error": {"code": "VALIDATION_ERROR", ...}}

Gestion d'Erreurs JavaScript SDK

try {
  const secret = await client.createSecret("content", {
    hours: 25000  // Invalide
  });
} catch (error) {
  console.log(error.code);        // "VALIDATION_ERROR"
  console.log(error.message);     // Message lisible par l'humain
  console.log(error.details);     // Détails de validation
  
  // Gérer des erreurs spécifiques
  if (error.code === 'QUOTA_EXCEEDED') {
    console.log('Améliorez votre plan pour créer plus de secrets');
  }
}

Gestion d'Erreurs Python SDK

try:
    secret = await client.create("content", hours=25000)
except sharokey.ValidationError as e:
    print(f"Validation échouée : {e.details}")
except sharokey.QuotaExceededError as e:
    print(f"Quota dépassé : {e.message}")
except sharokey.SharokeyError as e:
    print(f"Erreur API : {e.code} - {e.message}")

🔧 Meilleures Pratiques de Gestion d'Erreurs

Dégradation Gracieuse

JavaScript SDK

async function createSecretWithFallback(content, options) {
  try {
    return await client.createSecret(content, options);
  } catch (error) {
    if (error.code === 'QUOTA_EXCEEDED') {
      // Fallback : Stocker localement ou mettre en file d'attente pour plus tard
      return await storeLocally(content, options);
    }
    throw error; // Re-lancer d'autres erreurs
  }
}

Python SDK

async def create_secret_with_retry(content, **options):
    max_retries = 3
    for attempt in range(max_retries):
        try:
            return await client.create(content, **options)
        except sharokey.RateLimitError as e:
            if attempt < max_retries - 1:
                await asyncio.sleep(2 ** attempt)  # Backoff exponentiel
                continue
            raise
        except sharokey.SharokeyError:
            raise  # Ne pas réessayer sur d'autres erreurs

Journalisation d'Erreurs

function logSharokeyError(error, context = {}) {
  const logEntry = {
    timestamp: new Date().toISOString(),
    level: 'ERROR',
    source: 'sharokey-sdk',
    error: {
      code: error.code,
      message: error.message,
      details: error.details
    },
    context
  };
  
  console.error(JSON.stringify(logEntry));
  
  // Alerter sur les erreurs critiques
  if (error.code === 'INTERNAL_ERROR') {
    notifySupport(logEntry);
  }
}

Messages Conviviaux

function getErrorMessage(error) {
  const messages = {
    'VALIDATION_ERROR': 'Veuillez vérifier votre saisie et réessayer.',
    'QUOTA_EXCEEDED': 'Vous avez atteint votre limite de plan. Considérez un upgrade.',
    'RATE_LIMIT_EXCEEDED': 'Trop de requêtes. Veuillez attendre un moment.',
    'NOT_FOUND': 'Le secret que vous cherchez n\'existe pas ou a expiré.',
    'AUTHENTICATION_ERROR': 'Veuillez vérifier la configuration de votre token API.'
  };
  
  return messages[error.code] || 'Une erreur inattendue s\'est produite. Veuillez réessayer.';
}

🔗 Documentation Liée

• Authentification - Gestion et configuration sécurisées des tokens
• Limites de Taux - Comprendre les limites d'utilisation API
• Documentation CLI C# - Gestion d'erreurs en ligne de commande
• JavaScript SDK - Gestion d'erreurs navigateur et Node.js
• Python SDK - Patterns de gestion d'erreurs asynchrones

---

Tous les SDK implémentent une gestion automatique des erreurs, une logique de nouvelle tentative et fournissent des objets d'erreur structurés pour un débogage facile.