Erreurs
L’enveloppe d’erreur, tous les codes et ceux qui justifient une nouvelle tentative.
Toutes les erreurs ont la même structure :
{
"error": {
"type": "not_found_error",
"code": "resource_not_found",
"message": "This site does not exist.",
"docs_url": "https://atelier201.com/docs/api/errors#resource_not_found"
},
"request_id": "req_01K9X7"
}Basez votre logique sur code, jamais sur message. Les codes font partie du contrat ; les messages sont destinés aux utilisateurs et peuvent évoluer. Certaines erreurs incluent un objet details avec les informations nécessaires pour agir, par exemple la révision actuelle après un conflit d’écriture.
Quelles erreurs réessayer
| Status | Réessayer ? |
|---|---|
| 429 | Oui, après Retry-After. |
| 5xx | Seulement pour une requête idempotente (GET, PUT, DELETE). Une requête POST qui échoue avec une erreur 5xx a peut-être déjà été appliquée. Relisez d’abord la ressource. |
| 4xx | Non. La requête est incorrecte et le sera encore. |
Tous les codes
authentication_required
authentication_error · HTTP 401
Aucun identifiant d’authentification n’a été envoyé. Ajoutez un en-tête Authorization: Bearer.
invalid_api_key
authentication_error · HTTP 401
L’identifiant d’authentification n’est pas reconnu. Il peut appartenir à un espace de travail qui n’existe plus.
api_key_expired
authentication_error · HTTP 401
La clé a dépassé sa date d’expiration. Créez-en une nouvelle.
api_key_revoked
authentication_error · HTTP 401
La clé a été révoquée. Cette révocation est définitive.
insufficient_scope
permission_error · HTTP 403
L’identifiant d’authentification est valide, mais n’a pas reçu l’autorisation requise par ce point de terminaison. Le message précise laquelle. Émettez un nouvel identifiant d’authentification : il est impossible d’élargir les autorisations de celui-ci.
feature_not_available
permission_error · HTTP 403
Cette fonctionnalité n’est pas incluse dans le forfait. Pour la publication d’un brouillon, details.blockers contient plan_required et action_url ouvre la page du forfait du site.
admin_required
permission_error · HTTP 403
Cette action est réservée aux administrateurs de l’espace de travail : publier, revenir à une version antérieure, mettre un site hors ligne, supprimer un site et modifier ses domaines.
invalid_request
invalid_request_error · HTTP 400
Le corps de la requête ou la requête de recherche n’est pas valide. Le message indique le champ concerné.
unknown_field
invalid_request_error · HTTP 400
Un champ non accepté par ce point de terminaison a été envoyé. Les entrées sont volontairement strictes : un champ ignoré sans avertissement pourrait entraîner un problème découvert beaucoup plus tard.
invalid_parameter
invalid_request_error · HTTP 400
Un paramètre n’a pas le bon format, généralement parce que l’identifiant est mal formé.
invalid_cursor
invalid_request_error · HTTP 400
Le curseur de pagination n’a pas été émis par notre système. Recommencez la liste depuis le début.
request_too_large
invalid_request_error · HTTP 413
Le corps de la requête dépasse la limite absolue.
resource_not_found
not_found_error · HTTP 404
Aucun objet de ce type dans cet espace de travail. Une ressource appartenant à un autre espace de travail renvoie également cette erreur, volontairement : les distinguer permettrait de découvrir quels identifiants existent.
conflict
conflict_error · HTTP 409
La ressource existe et la requête est bien formée, mais son état actuel interdit l’action. Contrairement à une erreur 400, l’action pourra réussir plus tard. Causes fréquentes :
- Un conflit d’écriture. Quelqu’un a modifié un fichier depuis que vous l’avez lu.
details.reasonvautrevision_conflict,details.current_revisionindique la révision à lire etdetails.pathsrépertorie chaque fichier avec le hachage attendu et celui détecté. - Une publication basée sur une révision obsolète ou une génération qui ne peut pas être mise en ligne. Relancez la vérification et consultez
details.blockers. - Une limite de forfait, par exemple trop de brouillons ou un domaine non compris dans le forfait. Le message précise la limite, et
action_urlrenvoie vers la page permettant de la lever.
result_not_ready
conflict_error · HTTP 409
L’opération n’est pas terminée, par exemple lorsqu’un site est encore en cours de création. Attendez quelques secondes au lieu de réessayer immédiatement.
idempotency_key_reused
conflict_error · HTTP 409
La clé Idempotency-Key envoyée à un point de terminaison qui l’accepte a déjà été utilisée pour une autre requête dans cet espace de travail. Aucune action n’a été effectuée. Utilisez une nouvelle clé pour une nouvelle opération ; si vous renvoyez la même requête avec la même clé, la première réponse vous sera renvoyée.
insufficient_credits
invalid_request_error · HTTP 402
Crédits insuffisants. Arrêtez-vous et prévenez une personne ; réessayer ne servira à rien.
request_too_large_for_plan
invalid_request_error · HTTP 422
Le corps de la requête respecte la limite absolue, mais dépasse celle autorisée par ce forfait.
result_expired
not_found_error · HTTP 410
Le résultat a été supprimé conformément à la politique de conservation. Il ne sera pas rétabli.
rate_limited
rate_limit_error · HTTP 429
Trop de requêtes. Attendez la durée indiquée par Retry-After avant de réessayer. Cette même durée figure dans le corps sous forme de données : details.retry_after_seconds et details.retry_at (une date ISO), ainsi que dans les erreurs d’outils MCP et la sortie JSON de la CLI.
internal_error
api_error · HTTP 500
Une erreur s’est produite de notre côté. Indiquez le request_id.
service_unavailable
api_error · HTTP 503
Un service dont dépend cette opération est en panne ou en maintenance. Réessayez après un délai.