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/minds",
  "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": "Starter plan limit reached",
  "message": "Starter plan limit reached",
  "url": "/api/v1/minds",
  "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": "Mind 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

Consultez le tableau généré des limites pour les valeurs publiques actuelles. Les ajustements contractuels peuvent différer ; data.limit et data.current dans une erreur authentifiée font donc foi pour cette requête. L'offre Starter apparaît comme "premium" dans les payloads API.

Exemple de limite de Minds

Erreur lorsque la limite est atteinte :

{
  "statusCode": 403,
  "statusMessage": "Starter plan limit reached",
  "message": "Starter plan limit reached",
  "url": "/api/v1/minds",
  "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.

Échecs de validation d’Audience

Lancer une validation d’Audience sur une Audience de moins de 10 Minds prêts renvoie 422 avec le code AUDIENCE_TOO_SMALL. Une Audience plus grande que ce que votre offre autorise dans une Étude est refusée avec l’erreur standard de limite d’offre décrite plus haut.

Après un lancement réussi, la validation s’exécute en arrière-plan : la plupart des échecs ne sont donc pas des erreurs HTTP. Lisez-les plutôt dans le champ failure du lot de validation. Un lot peut se terminer avec l’un de ces codes :

Bonnes pratiques

Gestion des erreurs

Gérez toujours les erreurs :

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

  const text = await response.text();
  let result = null;
  if (text) {
    try {
      result = JSON.parse(text);
    } catch {
      if (response.ok) throw new Error('Expected a JSON response');
    }
  }
  if (!response.ok) {
    throw Object.assign(new Error(result?.statusMessage || result?.message || `HTTP ${response.status}`), {
      status: response.status,
      data: result?.data,
      retryAfter: response.headers.get('Retry-After')
    });
  }
  return result;
}

Logique de nouvelle tentative

Mettez en place des retries intelligents :

• Réessayez les lectures après une réponse temporaire 429 ou 5xx, avec un nombre limité de tentatives, un délai exponentiel et le respect de Retry-After. Ne réessayez une écriture que si le point de terminaison garantit son idempotence, avec la même clé et le même corps. Après un délai dépassé ambigu, vérifiez la ressource ou la tâche existante avant de soumettre à nouveau.
• 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 :

• État du service Minds
• 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
• Minds 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