Docs
Tableau de bord

Erreurs

Toutes les réponses d'erreur de l'API Scrumball utilisent la même enveloppe JSON : success vaut false, code porte le statut HTTP et message une brève explication. Les sections ci-dessous expliquent ce que signifie chaque statut, ce qui le déclenche et comment le résoudre.

Format des réponses d'erreur

json
{
  "success": false,
  "code": 400,
  "message": "Bad Request"
}

400Bad Request

Signification

Le serveur n'a pas pu analyser ou accepter la requête ; elle a été rejetée avant d'atteindre la logique métier.

Causes fréquentes

  • Le corps de la requête n'est pas un JSON valide (endpoints POST comme search ou la création de tâches de suivi).
  • Content-Type n'est pas défini sur application/json.
  • Un paramètre de requête a un format incorrect, par exemple une date au mauvais format.
  • Une faute de frappe dans le chemin a conduit à la mauvaise route.

Comment corriger

  1. Vérifiez que le chemin et la méthode HTTP correspondent à la page de référence du point de terminaison.
  2. Pour les endpoints POST, vérifiez que la requête contient Content-Type: application/json.
  3. Passez le corps dans un validateur JSON pour confirmer qu'il est analysable.
  4. Parcourez le tableau des paramètres obligatoires de la page du point de terminaison et vérifiez chaque nom et format.

401Unauthorized

Signification

La requête ne contient pas de clé API valide ; le serveur ne peut pas identifier l'appelant.

Causes fréquentes

  • L'en-tête Authorization n'a pas été envoyé.
  • Un préfixe Bearer a été ajouté devant la clé (cette API attend la clé brute, sans préfixe).
  • La clé a été supprimée ou renouvelée et le client utilise encore l'ancienne valeur.
  • La clé a été copiée avec un espace ou un saut de ligne.

Comment corriger

  1. Vérifiez que l'en-tête est exactement Authorization: YOUR_API_KEY, sans préfixe.
  2. Vérifiez dans Tableau de bord > API Keys que la clé est toujours active.
  3. Si la clé n'est plus valide, créez-en une nouvelle et mettez à jour la variable d'environnement côté serveur.
  4. Vérifiez d'abord la connectivité avec GET /api/ping, puis déboguez le point de terminaison concerné.

403Forbidden

Signification

L'appelant a été identifié, mais le compte n'a pas le droit d'utiliser ce point de terminaison ou son quota est épuisé.

Causes fréquentes

  • Le forfait actuel n'inclut pas ce point de terminaison (par exemple l'analyse d'audience ou la collecte temps réel).
  • Le quota d'essai est épuisé.
  • L'abonnement a expiré.
  • Le point de terminaison n'est pas encore activé pour ce compte.

Comment corriger

  1. Consultez le quota restant dans Tableau de bord > Usage.
  2. Vérifiez l'état de l'abonnement et les points de terminaison couverts dans Tableau de bord > Billing.
  3. Pour accéder à des points de terminaison de niveau supérieur, changez de forfait ou contactez le support.
  4. Distinguez 403 et 429 : 403 est un problème de droits, 429 une limite de débit.

404Not Found

Signification

Le chemin demandé n'existe pas, ou la ressource demandée n'a aucun enregistrement en base.

Causes fréquentes

  • Le chemin du point de terminaison est mal orthographié ou obsolète.
  • La méthode HTTP ne correspond pas (par exemple une requête GET vers un endpoint POST).
  • Le compte créateur n'est pas couvert par la base persistée.
  • La vidéo ou la publication a été supprimée ou rendue privée.

Comment corriger

  1. Vérifiez le chemin complet et la méthode par rapport à la page de référence du point de terminaison.
  2. Assurez-vous que l'URL de base est https://openapi.scdata.cc, et non le domaine du site de documentation.
  3. Si un compte reste introuvable, appelez le point de terminaison temps réel correspondant pour déclencher une collecte.
  4. Distinguez un 404 d'une réponse 200 avec data: null — cette dernière signifie que le chemin est correct mais qu'il n'y a pas de données.

429Too Many Requests

Signification

Le débit des requêtes a dépassé la limite du forfait actuel et le serveur a appliqué une limitation.

Causes fréquentes

  • Trop de requêtes simultanées en même temps.
  • Un traitement par lots sans limitation a envoyé une rafale de requêtes en peu de temps.
  • Plusieurs instances de service partagent une même clé sans coordonner leur cadence d'appel.
  • La logique de reprise n'a pas de délai d'attente : les tentatives immédiates après un échec amplifient la charge.

Comment corriger

  1. Réduisez la concurrence et plafonnez le nombre de requêtes par unité de temps.
  2. Mettez en place un délai exponentiel : attendez 1 seconde, puis doublez à chaque fois, avec un plafond recommandé de 32 secondes.
  3. Pour les traitements par lots, consommez depuis une file d'attente afin de maîtriser le débit.
  4. Examinez la courbe de consommation dans Tableau de bord > Usage pour repérer les périodes de pointe.

500Server Error

Signification

Le serveur a rencontré une exception inattendue en traitant la requête ; la requête elle-même n'est pas en cause.

Causes fréquentes

  • Une source de données d'une plateforme en amont est temporairement indisponible.
  • Une exception interne du serveur.
  • Une combinaison de paramètres particulière a déclenché un cas limite non géré.

Comment corriger

  1. Réessayez avec un délai d'attente ; l'erreur disparaît généralement après une courte pause.
  2. Enregistrez le contexte complet de la requête : chemin, paramètres, heure et corps de la réponse.
  3. Si la même requête échoue systématiquement, contactez le support avec ce contexte.
  4. Traitez les 5xx et les 4xx différemment côté client : les 5xx peuvent être réessayés, les 4xx exigent de corriger la requête.