Intégration 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."
}
ChampContenu
errorCode stable, lié au statut HTTP
messageTexte en français pour une personne ; il peut changer
reasonFacultatif : prérequis manquant pour lancer un audit
existingRunFacultatif : 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#

StatuterrorCasRéessayer ?
401unauthenticatedClé absente, mal formée, invalide, expirée ou révoquée ; compte inactifNon : changez de clé
403forbiddenScope absent ou rôle actuel du propriétaire insuffisantNon : ajustez les droits
404not_foundRessource inexistante ou hors du périmètre de la cléNon
409conflictÉtat incompatible, issue déjà traitée, corps différent pour la même Idempotency-KeyNon, sauf après changement d'état
422invalid_requestIdentifiant mal formé, pagination, corps JSON, champ inconnu, Idempotency-Key invalide, période invalideNon : corrigez la requête
429rate_limitedQuota de la clé dépassé pour ce projetOui, après Retry-After secondes
503unavailableCapacité désactivée ou service indisponibleOui, 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.

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.

StatutreasonQui corrige
503repository_audits_disabledL'exploitant active les audits sur l'instance (voir GitHub App et interrupteurs)
409repository_stoppedLe Responsable coche « Autoriser les travaux sur ce dépôt »
409repository_not_boundLe 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.