# Erreurs de l'API

Une erreur répond avec un statut HTTP `4xx` ou `5xx`, et un objet `error`. Le champ `code` est stable : teste-le dans ton code. Le champ `message` est en français et s’affiche à une personne.

```json
{
  "error": {
    "code": "not_found",
    "message": "Projet introuvable."
  }
}
```

## Codes

| Statut | Code                    | Cause                                                                                                    | Que faire                                                                               |
| ------ | ----------------------- | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `400`  | `bad_request`           | Corps ou paramètre invalide. Le message nomme le champ en cause                                          | Corrige la requête                                                                      |
| `400`  | `missing_files`         | Des fichiers du déploiement ne sont pas encore envoyés. La réponse liste leurs empreintes dans `missing` | Envoie-les par [`/v2/files`](/docs/reference/api/fichiers/), puis recrée le déploiement |
| `400`  | `invalid_digest`        | Le contenu envoyé ne correspond pas à l’empreinte annoncée                                               | Recalcule le SHA1 du fichier                                                            |
| `403`  | `forbidden`             | Clé absente, inconnue ou révoquée. Ou clé de projet utilisée pour un autre projet                        | Vérifie la clé et sa portée                                                             |
| `404`  | `not_found`             | Ressource introuvable, ou hors de la portée de la clé                                                    | Vérifie l’identifiant ou le nom                                                         |
| `409`  | `conflict`              | Un projet porte déjà ce nom                                                                              | Choisis un autre nom, ou utilise le projet existant                                     |
| `409`  | `deployment_closed`     | Le déploiement a été annulé ou a échoué : rien n’est publié                                              | Crée un nouveau déploiement                                                             |
| `413`  | `file_too_large`        | Un fichier dépasse 20 Mo                                                                                 | Allège le fichier, ou sers-le autrement                                                 |
| `413`  | `payload_too_large`     | Les fichiers inclus dans le corps dépassent 20 Mo au total                                               | Envoie-les par [`/v2/files`](/docs/reference/api/fichiers/)                             |
| `429`  | `rate_limited`          | Trop de requêtes pour cette clé                                                                          | Attends un instant, puis réessaie                                                       |
| `500`  | `internal_server_error` | Erreur de la plateforme. Elle est signalée automatiquement                                               | Réessaie. Si elle persiste, écris à <support@hgdc.ch>                                   |

Toutes les routes peuvent répondre `403 forbidden`, `429 rate_limited` et `500 internal_server_error`.

Le message d’une erreur `500` ne donne jamais de détail technique. Ne compte pas sur son texte, seulement sur son code.

## Le cas de missing_files

`missing_files` n’est pas une panne : c’est l’étape normale d’un déploiement. La CLI la traite toute seule. Si tu écris ton propre client, voici la réponse :

```json
{
  "error": {
    "code": "missing_files",
    "message": "Fichiers à envoyer avant de créer le déploiement.",
    "missing": [
      "2ef7bde608ce5404e97d5f042f95f89f1c232871"
    ]
  }
}
```

Envoie chaque fichier listé, puis renvoie exactement la même requête de [création de déploiement](/docs/reference/api/deploiements/).