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é.

{
  "ok": false,
  "error": "API_NOT_SET",
  "message": "The API token is not set correctly !"
}

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.

{
  "ok": false,
  "error": "PREMIUM_REQUIRED",
  "message": "This endpoint is reserved for Premium servers !"
}

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.

{
  "ok": false,
  "error": "MISSING_IDENTIFIER",
  "message": "Provide either discord_id or external_id !"
}

---

MULTIPLE_IDENTIFIERS

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

{
  "ok": false,
  "error": "MULTIPLE_IDENTIFIERS",
  "message": "You must provide only one identifier at a time !"
}

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 :

{
  "errors": [
    {
      "rule": "minLength",
      "field": "api_token",
      "message": "minLength validation failed"
    }
  ]
}

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.

{
  "ok": false,
  "error": "INVALID_DATE",
  "message": "Les dates doivent être au format ISO."
}

Exemple valide :

2026-06-01T00:00:00.000Z

---

INVALID_DATE_RANGE

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

{
  "ok": false,
  "error": "INVALID_DATE_RANGE",
  "message": "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.

{
  "ok": false,
  "error": "DATE_RANGE_TOO_LARGE",
  "message": "La période demandée ne peut pas dépasser 31 jours."
}

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.

{
  "ok": false,
  "error": "INVALID_CURSOR",
  "message": "Le curseur fourni est invalide."
}

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

{
  "pagination": {
    "next_cursor": "eyJjcmVhdGVkX2F0Ijoi..."
  }
}

---

INVALID_USER_ID

L’identifiant Discord fourni est invalide.

{
  "ok": false,
  "error": "INVALID_USER_ID",
  "message": "L'identifiant utilisateur Discord est invalide."
}

Cette erreur peut être retournée par :

GET /guild/votes/users/{user_id}

---

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.