Une erreur répond avec un statut HTTP et un objet JSON error : un code, un message, et pour certaines erreurs data. Le code est stable, si bien que votre logiciel peut s’y fier ; le message s’adresse aux personnes, et sa formulation peut changer.
{
"error": {
"code": "permission-denied",
"message": "Missing required scope: invoices:read"
}
}Codes de statut
| Statut | Code | Quand |
|---|---|---|
| 400 | invalid-argument |
Un paramètre, le corps ou un curseur est invalide ; data liste les problèmes d’un paramètre ou du corps. |
| 401 | unauthenticated |
La clé est absente, inconnue, révoquée ou expirée. |
| 403 | permission-denied |
La clé n’a pas la portée, ou son utilisateur n’a pas la permission dans l’espace de travail. |
| 404 | not-found |
La ressource n’existe pas. |
| 409 | aborted ou already-exists |
Une règle de Sway a refusé l’opération, comme un espace de travail suspendu ; data.name nomme la règle. |
| 429 | resource-exhausted, ou pas de corps JSON |
Trop de requêtes : voir la limite de requêtes ci-dessous. |
| 500 | internal ou failed-precondition |
Une erreur inattendue, ou une ressource qui n’est pas dans l’état que l’opération exige. La production masque le message d’une erreur inattendue. |
| 503 | unavailable |
Un service dont Sway a besoin est indisponible un instant. |
Les détails d’un refus
Quand une règle de Sway refuse une opération, data porte le name de cette règle, qui reste le même quand le message change, et la trace de la requête quand il y en a une. Donnez la trace à l’équipe support quand vous posez une question sur une erreur.
{
"error": {
"code": "aborted",
"message": "Workspace is suspended",
"data": {"name": "business/workspace-suspended", "trace": "…"}
}
}Un espace de travail est suspendu une fois son abonnement terminé. Chaque appel sur ses données répond alors 409 avec business/workspace-suspended, lectures comprises, jusqu’à ce que l’abonnement soit de nouveau actif.
Limite de requêtes
Sway accepte jusqu’à 600 requêtes par minute depuis chaque adresse IP. Au-delà, il répond 429, sans corps JSON, jusqu’à la fin de la minute. Tous les programmes qui appellent depuis la même adresse se partagent cette limite.
Relancer sans risque
- Relancez un
429ou un503après une pause, et attendez plus longtemps après chaque tentative. - Ne répétez pas tel quel un
400, un401, un403ou un404: corrigez d’abord la requête, la clé ou ses portées. - Avant de répéter une écriture qui a expiré ou répondu
500, relisez la ressource : la première tentative l’a peut-être déjà modifiée.