Scopes et erreurs

Chaque opération de l'API publique exige un scope explicite. Un identifiant valide qui ne dispose pas de ce scope reçoit 403 insufficient_scope ; il n'est jamais élevé silencieusement vers un accès plus large.

Référence des scopes#

Utilisez des scopes en lecture pour les tâches de reporting. N'ajoutez un scope en écriture que si l'intégration effectue réellement cette modification. Par exemple, un export de leads nécessite normalement sites:read et leads:read, et non sites:write ou agents:write.

Échecs liés aux scopes#

{
  "error": {
    "code": "insufficient_scope",
    "message": "The API key does not grant the required scope.",
    "details": { "required": ["sites:write"] },
    "request_id": "6c0b2f2e-..."
  }
}

Ajoutez le scope manquant à la clé dans Paramètres → Développeur → Modifier, ou créez une clé de remplacement et mettez à jour le secret côté serveur. La modification change le nom et les scopes de la clé sur place ; son expiration et son jeton restent identiques. Les clés émises via OAuth ne peuvent pas être modifiées ; reconnectez l'application pour changer les autorisations qui lui ont été accordées.

Enveloppe d'erreur#

Toutes les erreurs de l'API utilisent la même structure de premier niveau :

type ApiError = {
  error: {
    code: string;
    message: string;
    details?: unknown;
    request_id: string;
  };
};

Basez votre logique sur error.code, et non sur le message en anglais. Les messages peuvent être améliorés sans changement de version. Consignez error.request_id et l'en-tête de réponse x-request-id avec le nom de l'opération, le statut et le numéro de la tentative, mais ne consignez jamais l'en-tête d'autorisation ni les secrets de la requête.

Référence des statuts et des codes#

Les ressources extérieures au compte du propriétaire de l'identifiant peuvent renvoyer 404 plutôt que de révéler si l'ID d'un autre tenant existe.

Détails de validation#

La validation des champs renvoie des chemins que vous pouvez afficher à côté de vos propres champs de formulaire :

{
  "error": {
    "code": "invalid_request",
    "message": "Request validation failed.",
    "details": [
      { "path": "content.headline", "message": "String must contain at least 1 character(s)" }
    ],
    "request_id": "6c0b2f2e-..."
  }
}

Les corps des requêtes de modification doivent être des objets JSON. Les tableaux, les corps vides, les données de formulaire et le JSON envoyé avec un type de contenu texte sont rejetés.

Décisions de nouvelle tentative#

• Réessayez une erreur 429 après le nombre de secondes indiqué dans Retry-After.
• Ne réessayez une erreur 500 que pour des lectures sûres ou des écritures protégées par la même Idempotency-Key.
• Réessayez l'erreur 409 d'idempotence « en cours » après le délai de l'en-tête Retry-After: 2.
• Ne réessayez jamais aveuglément une erreur 503 outcome_unknown. Vérifiez d'abord la ressource ; n'utilisez une nouvelle clé d'idempotence qu'après avoir confirmé que la modification n'a pas eu lieu.
• Ne réessayez pas les erreurs 400, 401, 403, 404, 413 ni un conflit d'état tant que la cause n'a pas changé.

Consultez Limites de débit pour le comportement de backoff et la Référence de l'API pour le scope requis par chaque opération.