Erreurs et limites

Comprendre les erreurs API, les rate limits et les restrictions des offres.

Format des réponses d'erreur

Toutes les erreurs suivent un format cohérent :

{
  "statusCode": 400,
  "statusMessage": "Name is required",
  "message": "Name is required",
  "url": "/api/v1/sparks",
  "error": true
}

Appuyez-vous toujours sur statusCode pour le traitement programmatique et sur statusMessage (ou message) pour la raison lisible. Les champs url et error sont des métadonnées de commodité fournies par le framework sous-jacent.

Codes de statut HTTP

2xx Succès

4xx Erreurs client

5xx Erreurs serveur

Erreurs courantes

400 Bad Request

Champ requis manquant :

{
  "statusCode": 400,
  "statusMessage": "Name is required"
}

Entrée invalide :

{
  "statusCode": 400,
  "statusMessage": "File too large: document.pdf (55.2MB). Maximum size is 50MB."
}

401 Unauthorized

Clé API manquante :

{
  "statusCode": 401,
  "statusMessage": "Unauthorized"
}

Solution : Incluez l'en-tête Authorization :

-H "Authorization: Bearer minds_your_api_key"

403 Forbidden

Limite d'offre atteinte :

{
  "statusCode": 403,
  "statusMessage": "Individual plan limit reached",
  "message": "Individual plan limit reached",
  "url": "/api/v1/sparks",
  "error": true,
  "data": {
    "code": "PLAN_LIMIT",
    "limitType": "sparks",
    "currentPlan": "premium",
    "limit": 100,
    "current": 100
  }
}

Accès refusé :

{
  "statusCode": 403,
  "statusMessage": "Access denied"
}

404 Not Found

La ressource n'existe pas :

{
  "statusCode": 404,
  "statusMessage": "Spark not found"
}

415 Unsupported Media Type

Content-Type incorrect :

{
  "statusCode": 415,
  "statusMessage": "Unsupported Content-Type. Use application/json for links or multipart/form-data for files"
}

Solution : Utilisez le bon en-tête Content-Type :

• application/json pour les requêtes JSON
• multipart/form-data pour les téléversements de fichiers

429 Too Many Requests

Rate limit dépassé :

{
  "statusCode": 429,
  "statusMessage": "Too many requests. Please try again later."
}

Rate limits

L'API v1 applique une fenêtre fixe par compte authentifié. La limite de déploiement par défaut est de 300 requêtes par minute, mais elle est configurable. Lisez toujours RateLimit-Limit et RateLimit-Remaining ; après un 429, attendez le nombre de secondes indiqué par Retry-After.

Limites d'offre

Les différentes offres ont des limites de ressources différentes.

Limites de minds

Erreur lorsque la limite est atteinte :

{
  "statusCode": 403,
  "statusMessage": "Individual plan limit reached",
  "message": "Individual plan limit reached",
  "url": "/api/v1/sparks",
  "error": true,
  "data": {
    "code": "PLAN_LIMIT",
    "limitType": "sparks",
    "currentPlan": "premium",
    "limit": 100,
    "current": 100
  }
}

Limites de téléversement de connaissance

• Taille de fichier : Maximum 50 Mo par fichier (toutes offres)
• Stockage : Pas de limite de stockage explicite actuellement imposée

Limites de clés API

• Clés maximum : Aucune limite n'est actuellement appliquée.

Bonnes pratiques

Gestion des erreurs

Gérez toujours les erreurs :

try {
  const response = await fetch(url, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(data)
  });

  if (!response.ok) {
    const error = await response.json();
    console.error(`Error ${error.statusCode}: ${error.message}`);
    // Handle specific errors
    if (error.statusCode === 429) {
      // Implement retry logic
    }
  }

  const result = await response.json();
  return result;
} catch (error) {
  console.error('Network error:', error);
}

Logique de nouvelle tentative

Mettez en place des retries intelligents :

• Réessayez sur les erreurs 429 (rate limit) et 5xx
• Utilisez un backoff exponentiel
• Définissez un nombre maximum de tentatives
• Ne réessayez pas sur les erreurs 4xx (sauf 429)

Surveillance

Suivez votre utilisation :

• Loggez les en-têtes de rate limit
• Surveillez les taux d'erreur
• Configurez des alertes pour les erreurs récurrentes
• Suivez les temps de réponse

Effectuez une mise à niveau au besoin

Passez à une offre supérieure si vous :

• Atteignez fréquemment les rate limits
• Avez besoin de plus de minds
• Nécessitez des téléversements de fichiers plus volumineux
• Souhaitez un support prioritaire

Voir les offres

Obtenir de l'aide

Vérifier le statut

Surveillez l'état de notre service :

• Page de statut (à venir)
• Suivez @mindsai_co pour les mises à jour

Contacter le support

Si vous rencontrez :

• Des erreurs 500 persistantes
• Un rate limiting incorrect
• Un comportement inattendu

Contactez-nous :

• Formulaire de retour
• E-mail : [email protected]

Consulter la documentation

• API Overview
• Authentication
• Sparks API
• Knowledge API
• Chat API

Référence des codes de statut

Référence rapide pour tous les codes de statut HTTP :

2xx Success
├─ 200 OK
└─ 201 Created

4xx Client Error
├─ 400 Bad Request
├─ 401 Unauthorized
├─ 403 Forbidden
├─ 404 Not Found
├─ 415 Unsupported Media Type
└─ 429 Too Many Requests

5xx Server Error
├─ 500 Internal Server Error
└─ 503 Service Unavailable