Erreurs et codes d’état
Les erreurs sont du JSON, toujours de la même forme, et portent toujours un code stable lisible par machine. Branchez sur le code, pas sur le message.
La forme
Tout échec renvoie un objet avec un error lisible par un humain et un code stable. Le message est écrit pour une personne et peut être reformulé ; le code est un engagement et ne changera pas dans votre dos.
{
"error": "That file is larger than the 200 MB limit on your plan.",
"code": "VALIDATION_FAILED"
}Codes à gérer
| Code | HTTP | Signification |
|---|---|---|
| NOT_AUTHENTICATED | 401 | Jeton bearer absent ou mal formé |
| FORBIDDEN | 403 | La clé est valide mais n’a pas le droit de faire cela |
| NOT_ENTITLED | 402 | L’offre du compte n’inclut pas l’accès à l’API |
| VALIDATION_FAILED | 400 / 413 | Requête incorrecte, conversion non prise en charge, ou fichier trop volumineux |
| NOT_FOUND | 404 | Tâche inexistante, ou appartenant à un autre compte |
| RATE_LIMITED | 429 | Limite horaire atteinte. Attendez et réessayez. |
| INTERNAL | 500 | Quelque chose a cassé de notre côté. Réessayer est sans risque. |
Ce qu’il vaut la peine de réessayer
429 et 500 méritent une nouvelle tentative, avec un délai — en espaçant plutôt qu’en bouclant, car les tentatives comptent dans votre limite horaire comme toute autre requête.
Tout le reste est définitif pour cette requête. Réessayer un 400, un 402 ou un 404 donne la même réponse et consomme votre quota pour rien.
Un 502 ou 503 sans corps JSON ne vient pas de l’application — c’est le proxy placé devant, et là il vaut toujours la peine de réessayer.