---
title: Erreurs
description: Codes HTTP, codes d'erreur stables et conduite à tenir pour chaque refus de l'API.
---

# Erreurs

Toute erreur de l'API renvoie un statut HTTP et un corps JSON au même format. Votre outil décide de la suite d'après le statut et le champ `error`, jamais d'après le texte du message.

**Qui peut le faire** : tout outil qui appelle l'API.

## Format

```json
{
  "error": "conflict",
  "message": "Conflit avec l’état actuel ou une requête idempotente différente."
}
```

| Champ | Contenu |
| --- | --- |
| `error` | Code stable, lié au statut HTTP |
| `message` | Texte en français pour une personne ; il peut changer |
| `reason` | Facultatif : prérequis manquant pour lancer un audit |
| `existingRun` | Facultatif : exécution existante, sur un conflit de demande d'exécution |

Toutes les réponses de l'API portent `Cache-Control: no-store`, `X-Content-Type-Options: nosniff` et `Referrer-Policy: no-referrer`.

## Codes et conduite à tenir

| Statut | `error` | Cas | Réessayer ? |
| --- | --- | --- | --- |
| 401 | `unauthenticated` | Clé absente, mal formée, invalide, expirée ou révoquée ; compte inactif | Non : changez de clé |
| 403 | `forbidden` | Scope absent ou rôle actuel du propriétaire insuffisant | Non : ajustez les droits |
| 404 | `not_found` | Ressource inexistante ou hors du périmètre de la clé | Non |
| 409 | `conflict` | État incompatible, issue déjà traitée, corps différent pour la même `Idempotency-Key` | Non, sauf après changement d'état |
| 422 | `invalid_request` | Identifiant mal formé, pagination, corps JSON, champ inconnu, `Idempotency-Key` invalide, période invalide | Non : corrigez la requête |
| 429 | `rate_limited` | Quota de la clé dépassé pour ce projet | Oui, après `Retry-After` secondes |
| 503 | `unavailable` | Capacité désactivée ou service indisponible | Oui, avec un délai croissant (sauf `reason` présent) |

Une réponse `401` porte aussi `WWW-Authenticate: Bearer realm="101maintain"`.

## Cas particuliers

### Exécution déjà existante

Une demande d'exécution pour une issue déjà traitée renvoie `409`. Si la clé détient aussi `runs:read`, le corps désigne la dernière tentative de l'issue :

```json
{
  "error": "conflict",
  "message": "Une exécution existe déjà pour cette issue.",
  "existingRun": {
    "id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
    "status": "running",
    "links": { "self": "/api/v1/runs/c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f" }
  }
}
```

Suivez `existingRun.links.self` au lieu de redemander. Sans `runs:read`, le conflit reste générique et ne révèle aucun identifiant.

Les autres `409` d'une demande d'exécution : issue fermée, dépôt arrêté, non rattaché à la GitHub App ou non surveillé. Voir [Surveillance et politique du dépôt](../02-projets-et-depots/05-surveillance-et-politique.md).

### Prérequis d'un audit

Une demande d'audit refusée pour un prérequis manquant porte un `reason`. Le `message` nomme le réglage à changer : transmettez-le à la bonne personne.

| Statut | `reason` | Qui corrige |
| --- | --- | --- |
| 503 | `repository_audits_disabled` | L'exploitant active les audits sur l'instance (voir [GitHub App et interrupteurs](../08-deploiement-et-exploitation/06-github-app-et-fonctionnalites.md)) |
| 409 | `repository_stopped` | Le Responsable coche « Autoriser les travaux sur ce dépôt » |
| 409 | `repository_not_bound` | Le Responsable lie le dépôt : [Lier le dépôt à la GitHub App](../02-projets-et-depots/04-liaison-github-app.md) |

Le refus `repository_audits_disabled` est renvoyé avant la validation du corps de la requête.

### Arrêt global

Pendant un arrêt global de l'organisation, une nouvelle demande d'exécution ou d'audit n'est pas refusée : elle reçoit `202` avec le champ `waiting: "organization_stop"`. Elle reste en file et démarre une seule fois après la levée. `GET /api/v1/runs/<runId>` et `GET /api/v1/audits/<auditId>` portent le même champ tant que le travail attend. Inutile de redemander : un rejeu avec la même `Idempotency-Key` renvoie le même identifiant. Les lectures et l'annulation restent possibles. Voir [Arrêt global](../06-administration-et-supervision/09-arret-global.md).

### Rapport final d'audit

`GET /api/v1/audits/<auditId>/report` renvoie `409` tant que l'audit n'est pas terminé, qu'un constat attend d'être qualifié ou qu'un contrôle dynamique est en cours. La qualification se fait dans l'interface : voir [Qualifier les constats](../04-audits-et-banc-d-essai/04-qualifier-les-constats.md).

### Rapport d'incident absent

`GET /api/v1/runs/<runId>/report` renvoie `404` si aucune édition PDF prête n'existe, sans distinguer « jamais demandée », « en file » ou « refusée ». Demandez à une personne de générer l'édition dans l'interface : voir [Rapports PDF](../05-rapports-usage-et-couts/01-rapports-pdf.md).

> [!NOTE]
> Si l'exploitant n'a pas activé les comptes sur l'instance, toute route `/api/v1` renvoie `404` avec le seul corps `{"error":"not_found"}`.

## Pour continuer

Passez aux exemples complets : [Recettes d'intégration](06-recettes.md).
