Erreurs
L’enveloppe d’erreur
Toute réponse non 2xx a la même forme. Branchez votre logique sur error.code, jamais sur le message. error.details dépend du code ; pour les refus d’une clé d’API, il contient un reason.
Le requestId figure aussi dans l’en-tête X-Request-Id de chaque réponse, réussie ou non. Communiquez-le lorsque vous contactez le support.
403 Forbidden
{ "error": { "code": "forbidden", "message": "This key is missing the codes:write scope", "details": { "reason": "missing_scope", "scope": "codes:write" }, "requestId": "req_7Hq2mK9xT4" }}Codes d’erreur
400validation_failedLe corps ou la requête a échoué à la validation. details est une liste de problèmes { path, message }.400bad_requestLa requête est bien formée mais ne peut pas être exécutée ; details.reason explique pourquoi.401unauthorizedLa clé est absente, mal formée, révoquée ou expirée.403forbiddenLa clé n’a pas le droit de faire cela : un scope manquant, une restriction de dossier ou d’IP, ou une route réservée à l’application. Voir details.reason.404not_foundAucun objet de ce type dans cet espace de travail, ou la clé ne peut pas le voir.409conflictUn slug ou un nom d’hôte est pris, ou une requête avec le même Idempotency-Key est encore en cours.422idempotency_conflictL’Idempotency-Key a déjà été utilisé avec un corps différent.410goneL’objet existait et a été supprimé ou libéré.413payload_too_largeLe corps ou l’envoi dépasse la limite de taille.429rate_limitedBudget par minute ou en rafale de l’espace de travail dépassé. Attendez Retry-After secondes.403plan_limit_reachedUne limite de l’offre (codes, lignes en masse, tâches…) est atteinte. details nomme la limite et l’utilisation.403feature_not_in_planL’offre de l’espace de travail n’inclut pas cette fonctionnalité (par exemple les webhooks sur Free).422unsafe_destinationLa destination n’a pas passé la vérification Google Web Risk et liste de blocage.500internalQuelque chose a échoué de notre côté. Réessayez avec un backoff ; communiquez le requestId si cela persiste.503unavailableTemporairement indisponible. Réessayez avec un backoff.Refus de clés d’API
details.reason des refus propres aux clés d’API.
403 forbiddenmissing_scopeLa clé n’a pas le scope de la route (details.scope), ou le rôle de son créateur ne l’autorise plus.403 forbiddensession_requiredLa route est réservée à l’application (facturation, membres, gestion des clés…) ; les clés ne peuvent pas l’appeler.403 forbiddenapi_key_folder_restrictedLa clé est limitée à certains dossiers (details.folderIds) et la requête en cible un autre.403 forbiddenip_not_allowedL’adresse de l’appelant est hors de la liste d’IP autorisées de la clé.400 bad_requesttest_mode_unavailableLes clés sk_test_ ne peuvent pas être créées : il n’existe pas encore de mode test. Utilisez un espace de travail distinct pour les tests.400 bad_requesttoo_many_api_keysL’espace de travail a déjà 50 clés actives (details.limit). Révoquez-en une d’abord.403 forbiddenscope_not_grantableVotre rôle ne peut pas accorder ces scopes (details.scopes), par exemple webhooks:write en tant qu’editor.Quoi réessayer
Réessayez un 429 après Retry-After secondes, et un 500 ou 503 avec un backoff exponentiel. Tout autre 4xx demande d’abord de modifier la requête. Les requêtes POST peuvent être réessayées sans risque quand vous envoyez le même Idempotency-Key.