--- title: "Erreurs" description: "L’enveloppe d’erreur, tous les codes et ceux qui justifient une nouvelle tentative." canonical: "https://atelier201.com/docs/fr/api/errors" updated: "2026-11-06" --- # Erreurs Toutes les erreurs ont la même structure : ```json { "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.reason` vaut `revision_conflict`, `details.current_revision` indique la révision à lire et `details.paths` ré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_url` renvoie 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.