For the complete documentation index, see llms.txt. This page is also available as Markdown.

Erreurs & codes de réponse

L’API DiscordTop renvoie toujours des réponses JSON, même en cas d’erreur.

Cette page répertorie l’ensemble des erreurs globales (communes à tous les endpoints), ainsi que celles spécifiques à la validation des paramètres.

Toutes les erreurs suivent la structure suivante :

{
  "ok": false,
  "error": "ERROR_CODE",
  "message": "Description de l'erreur."
}

📌 Codes d’erreur globaux

INVALID_API_TOKEN

Le token fourni ne correspond à aucun serveur Discord existant ou a été régénéré.

{
  "ok": false,
  "error": "INVALID_API_TOKEN",
  "message": "The provided API token is invalid !"
}

Causes possibles :

  • Token incorrect

  • Token expiré (rotation)

  • Token remplacé dans le tableau de bord

  • Token copié partiellement

  • Mauvaise guilde associée

  • La guilde associé possède actuellement une sanction


API_NOT_SET

Le token fourni n'est pas correctement configuré ou un placeholder non configuré.

Concerne souvent :

  • Une mauvaise génération de votre Token

  • Un CMS mal configuré

  • Une variable d’environnement manquante

  • Une intégration qui n’a pas renseigné la clé API


PREMIUM_REQUIRED

Le serveur lié au token API ne possède pas un abonnement Premium actif.

Rappel : Vous devez fournir exactement un identifiant pour vérifier un vote.

Vous faites un appel sur une route nécessitant l'abonnement Premium, attention, un délai d'activation peut-être nécessaire (1 heure max). En cas de non renouvellement, l'autorisation d'accès s'arrête également.


Erreurs liées aux identifiants utilisateur

Ces erreurs se produisent lorsque les paramètres discord_id et external_id sont mal utilisés.


MISSING_IDENTIFIER

Aucun identifiant n’a été fourni : ni discord_id, ni external_id.


MULTIPLE_IDENTIFIERS

Les deux identifiants ont été fournis en même temps.

Rappel : Un seul identifiant autorisé par requête :

  • Soit discord_id

  • Soit external_id

  • Mais pas les deux


Erreurs de validation des paramètres

Ces erreurs sont générées automatiquement par notre API lorsque les paramètres ne respectent pas le schéma attendu.

Exemple : ID trop court, trop long, format invalide…

Format général :

Important : Ces erreurs proviennent du validator et peuvent varier en fonction de votre implémentation future. Elles sont distinctes des erreurs API “contractuelles”.

Erreurs liées aux votes

INVALID_DATE

Une date fournie est invalide ou n’est pas au format ISO.

Exemple valide :


INVALID_DATE_RANGE

La date from doit être antérieure à la date to.


DATE_RANGE_TOO_LARGE

La période demandée dépasse la limite autorisée.

Les routes de récupération des votes acceptent une période maximale de 31 jours.


INVALID_CURSOR

Le curseur de pagination fourni est invalide.

Les curseurs doivent être utilisés tels quels depuis la réponse précédente :


INVALID_USER_ID

L’identifiant Discord fourni est invalide.

Cette erreur peut être retournée par :


Erreur 404 — Jamais renvoyée en tant que JSON d’erreur

À noter : Dans le cas d’un api_token invalide, l'API renvoie un 401 Unauthorized, pas un 404.

C’est voulu pour éviter la confusion entre :

  • une ressource inexistante (404)

  • une authentification invalide (401)


Récapitulatif des codes d’erreur

Code
Signification

INVALID_API_TOKEN

La clé API ne correspond à nos critères de sécurité.

API_NOT_SET

Le token fourni est un placeholder non configuré.

MISSING_IDENTIFIER

Aucun identifiant (discord_id ou external_id) fourni.

MULTIPLE_IDENTIFIERS

Les deux identifiants ont été reçus.

PREMIUM_REQUIRED

Cette route est réservée aux serveurs ayant l'abonnement Premium.

(Validation errors)

Format ou longueur invalide, gérés par nos validateurs.

Bonnes pratiques

  • Stockez le dernier next_cursor pour récupérer la suite des votes.

  • Ne modifiez jamais manuellement un curseur.

  • Utilisez des dates ISO en UTC.

  • Limitez vos périodes de synchronisation à 31 jours maximum.

  • Gérez toujours les erreurs 401, 403 et 429.

  • Ne considérez pas un 403 PREMIUM_REQUIRED comme une erreur temporaire : le serveur doit être Premium pour accéder à la route.

Last updated