# 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

***

## **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 !"
}
```

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

***

***

###  `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”.

***

## **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.                      |
| *(Validation errors)*  | Format ou longueur invalide, gérés par nos validateurs.   |