Erreurs

Skoup utilise les codes HTTP usuels : 2xx pour un succès, 4xx quand la requête ne peut pas aboutir telle qu’envoyée, 5xx quand quelque chose a échoué de notre côté.

Toutes les erreurs ont la même forme :

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "The title field is required.",
    "param": "title",
    "doc_url": "https://docs.skoup.ai/fr/errors#parameter_invalid",
    "request_id": "req_7Hq2mXbN4kLp9sRt3vYw1Z"
  }
}

Types

Codes

authentication_required

401 — Aucun en-tête Authorization: Bearer …. Chaque requête doit porter une clé API.

invalid_api_key

401 — La clé n’existe pas ou est mal formée. Vérifiez que vous l’avez copiée entièrement, préfixe skoup_live_ ou skoup_test_ compris.

api_key_revoked

401 — La clé a été révoquée dans le dashboard. Créez-en une nouvelle : une clé révoquée ne revient jamais.

workspace_billing_blocked

402 — L’espace est bloqué pour la facturation : son essai s’est terminé sans abonnement, une facture reste impayée 15 jours après l’échec du paiement, ou son abonnement a pris fin. Tous les appels sont refusés jusqu’à ce qu’un propriétaire régularise depuis Plan & facturation dans le tableau de bord ; rien n’est perdu entre-temps.

plan_feature_unavailable

403 — L’endpoint relève d’une fonctionnalité que le plan de l’espace n’inclut pas (par exemple le trafic IA via GA4 ou la corrélation visibilité ↔ CA, à partir du plan Growth). Le message nomme le plan qui l’inclut. Un propriétaire peut changer de plan depuis Plan & facturation dans le tableau de bord ; rien de ce qui a déjà été mesuré n’est perdu. Les clés de test atteignent toutes les fonctionnalités.

capability_unavailable

403 — L’endpoint appartient à un module que le profil d’activité de la marque n’a pas : par exemple les commandes attribuées, la corrélation ou les write-backs d’une marque qui vend un logiciel ou tient un établissement physique plutôt que des produits. Lisez le vertical de la marque sur GET /v1/brands/{id} pour savoir quels modules s’appliquent. Rien à corriger sur la clé ni sur le plan : le module n’existe pas pour cette marque.

insufficient_scope

403 — La clé est valide mais n’a pas le scope exigé par cet endpoint (par exemple tasks:write pour POST …/tasks). Le message nomme le scope manquant. Voir les scopes.

resource_missing

404 — Aucun objet ne correspond à cet ID, l’ID a le mauvais préfixe, ou la clé est limitée à d’autres marques.

parameter_invalid

422 — Un paramètre manque ou est invalide. param le nomme et message explique pourquoi.

resource_read_only

422 — L’objet ne peut pas être modifié par l’API. Les produits synchronisés depuis une boutique (Shopify, feed…) sont en lecture seule dans Skoup : la boutique fait foi, corrigez-les là-bas.

quota_exceeded

422 — Un quota de votre plan est atteint — par exemple le nombre de requêtes actives ou de vérifications d’alerte par jour. param nomme le quota ; l’en-tête Skoup-Quota-* correspondant dit quand il se libère.

invalid_transition

422 — Le changement d’état demandé n’est pas permis depuis l’état actuel de l’objet. Les tâches, par exemple, avancent d’une colonne à la fois sur le tableau.

idempotency_key_reused

422 — L’Idempotency-Key a déjà servi avec un corps de requête différent. Voir Idempotence.

rate_limit_exceeded

429 — Trop de requêtes. Attendez le nombre de secondes indiqué par l’en-tête Retry-After. Voir Limites de débit.

api_error

500 — Une erreur inattendue du côté de Skoup. Elles sont rares et surveillées ; réessayer avec un backoff exponentiel est sans risque pour les GET et pour les écritures envoyées avec une Idempotency-Key.