Erreurs

La forme d'une erreur de l'API, les treize codes avec leur statut HTTP et ce qu'ils coûtent, et quoi faire de chacun.

Toute erreur de l'API a la même forme, quelle que soit la route. Cette page décrit cette forme, les treize codes possibles et ce que chacun coûte en crédits.

Une seule forme

{
  "error": {
    "name": "PARTNER_API",
    "message": "SCOPE_MISSING",
    "details": { "scope": "students:write" }
  }
}

name vaut toujours PARTNER_API. Le code est dans message : c'est lui que ton outil lit, avec le statut HTTP. details n'existe que pour deux codes. SCOPE_MISSING y met le périmètre à ajouter. VALIDATION y met une liste, dont la forme dépend de l'origine du refus :

un paramètre ou un corps refusé à l'entrée : des entrées { field, type, message }, ou { field, reason } pour un cursor invalide ;
un argument que le schéma d'une opération refuse : des entrées { path, message } ;
le refus de l'opération elle-même, ou une erreur 4xx survenue pendant son exécution : une liste de textes. Les opérations webhooks.* font exception : leur refus rend un objet, dont code nomme la raison et dont les autres champs la précisent (voir Webhooks).

Un JSON mal formé ou un corps trop gros donne un VALIDATION sans details. Les autres codes n'en portent jamais.

Les treize codes

Code	HTTP	Quand	Crédit
`UNAUTHORIZED`	401	Clé absente, inconnue ou révoquée.	gratuit
`PLAN_NOT_ELIGIBLE`	403	Ton offre n'ouvre pas l'API.	gratuit
`SCOPE_MISSING`	403	La clé n'a pas le périmètre demandé.	gratuit
`WRITE_NOT_ALLOWED`	403	Ton offre n'ouvre pas les écritures par clé API.	gratuit
`CREDITS_EXHAUSTED`	402	Plus de crédits ce mois-ci et aucune réserve.	gratuit
`RATE_LIMITED`	429	Trop d'appels : 10 par seconde, 300 par minute, 60 écritures et 20 suppressions par minute.	gratuit
`IDEMPOTENCY_MISMATCH`	409	Même Idempotency-Key, autre opération ou autre corps.	gratuit
`CONFLICT`	409	La même requête est en cours.	gratuit
`OPERATION_NOT_EXPOSED`	404	Cette opération n'est pas ouverte par l'API.	gratuit
`DRY_RUN_UNSUPPORTED`	400	Pas d'aperçu pour cette opération.	gratuit
`VALIDATION`	400	Paramètres ou corps invalides (413 si le corps dépasse 1 Mo).	facturé ; jamais débité pour un 413 ou un JSON mal formé ; remboursé si le schéma d'une opération refuse ses arguments
`NOT_FOUND`	404	Rien à cette adresse.	facturé, sauf chemin inconnu
`INTERNAL_ERROR`	500	Erreur de notre côté.	remboursé pour une lecture ; gardé pour une écriture ou une suppression

Ce qui reste facturé

Le crédit est débité avant l'exécution. Seules trois erreurs le gardent :

Sur une lecture, un paramètre refusé (limit=500) donne un 400 VALIDATION facturé. GET /events fait exception : une route gratuite ne facture jamais ses erreurs.
Sur une lecture comme sur une opération, une cible introuvable ou qui n'est pas la tienne donne un 404 NOT_FOUND facturé.
Sur une écriture ou une suppression, un 500 INTERNAL_ERROR garde son crédit : la modification a pu être enregistrée avant la panne.
Sur une opération, un argument que son schéma refuse est remboursé. Le refus de l'opération elle-même, ou une erreur 4xx survenue pendant son exécution, reste facturé : l'opération a tourné.

Un corps JSON invalide ou une Idempotency-Key refusée ne coûtent rien. Clés et crédits détaille le reste.

Que faire d'une erreur

400, 403, 404. Ne réessaie pas telle quelle : la requête, la clé ou l'offre est à corriger. details dit quoi.
401. Vérifie la clé, qui est peut-être révoquée.
402. Les appels reprennent à la remise à zéro mensuelle, ou dès qu'un pack est ajouté.
409. IDEMPOTENCY_MISMATCH veut une nouvelle Idempotency-Key. Pour CONFLICT, lis Écritures et idempotence.
429. Attends Retry-After secondes : voir Limites.
500. Réessaie un peu plus tard. Pour une écriture, garde la même Idempotency-Key.