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#
{
"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 :
{
"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.
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) |
| 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 |
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.
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.
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.
Pour continuer#
Passez aux exemples complets : Recettes d'intégration.