> For the complete documentation index, see [llms.txt](https://docs.discordtop.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.discordtop.net/api-reference/concepts-cles/erreurs-and-codes-de-reponse.md). # Erreurs & codes de réponse 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 : ```json { "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é. ```json { "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é. ```json { "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. ```json { "ok": false, "error": "PREMIUM_REQUIRED", "message": "This endpoint is reserved for Premium servers !" } ``` {% hint style="info" %} 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. {% endhint %} *** ## **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`. ```json { "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. ```json { "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 : ```json { "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. ```json { "ok": false, "error": "INVALID_DATE", "message": "Les dates doivent être au format ISO." } ``` Exemple valide : ```bash 2026-06-01T00:00:00.000Z ``` *** ### `INVALID_DATE_RANGE` La date `from` doit être antérieure à la date `to`. ```json { "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. ```json { "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. ```json { "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 : ```json { "pagination": { "next_cursor": "eyJjcmVhdGVkX2F0Ijoi..." } } ``` *** ### `INVALID_USER_ID` L’identifiant Discord fourni est invalide. ```json { "ok": false, "error": "INVALID_USER_ID", "message": "L'identifiant utilisateur Discord est invalide." } ``` Cette erreur peut être retournée par : ```bash 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.