Référence — erreurs

Comment l'API signale une erreur, et ce que veut dire chaque code de retour. Les messages propres à chaque route sont listés sur la page de la route.

Le corps d'une erreur

{ "error": "cet accès ne permet pas cela — il faut : schedule.read", "code": "forbidden" 
}

Décidez sur le code HTTP et sur code, jamais sur le texte : le texte des messages peut changer d'une version à l'autre, les codes non.

Deux cas n'ont pas ce corps : les réponses 204, qui n'ont pas de corps du tout — par exemple DELETE /api/partner/webhooks/:webhookId —, et les réponses CSV et HTML d'une feuille de présence, qui n'en ont un qu'en cas d'erreur.

Les codes de retour

Les valeurs de code

D'autres valeurs, plus précises, servent à l'application — par exemple series.until ou invite.already-member. Un programme qui ne les connaît pas s'en tient au code HTTP.

Corps illisible ou trop gros

Sur /api, le corps est lu avant que la clé soit vérifiée : une requête dont le corps est illisible est refusée, même sans clé.

Un 413 sur un dépôt d'emploi du temps ou de liste d'inscrits se règle en découpant l'envoi en plusieurs dépôts. Chaque cours est reconnu par sa référence, chaque inscrit par son courriel ou son téléphone : un dépôt découpé, ou rejoué, ne crée pas de doublon.

401 : non authentifié

Sous /api/institutions/:institutionId, une requête sans justificatif ne reçoit pas 401 mais 404 : pour qui n'est personne, l'établissement n'existe pas.

404 ou 409

Les deux codes ne disent pas la même chose, et la différence compte pour l'éditeur partenaire comme pour l'établissement :

• 404 : l'objet désigné n'existe pas pour l'appelant — ou son identifiant n'a pas la forme d'un uuid. Un uuid mal formé ne dit rien de ce qui existe.
• 409 : la requête est comprise, mais l'état actuel l'empêche. Pour une feuille de présence demandée avec une clé, 409 veut dire qu'aucune feuille n'existe pour cet identifiant à cet instant : attendez le webhook attendance.closed plutôt que de réessayer en boucle.

Messages par route