Erreurs - Pulse-Sell Développeurs

L’API utilise les codes HTTP standard. En cas d’échec, le corps contient toujours message, code et errors.

{
  "message": "Le nom est requis.",
  "code": "validation_failed",
  "errors": { "name": ["name est requis."] }
}

Branchez votre logique sur code, jamais sur le texte de message.

Codes HTTP

Statut	Signification	Que faire
200, 201, 204	Succès	Rien : lisez `data`. Un `204` n’a pas de corps.
400	Corps JSON illisible (`invalid_body`)	Corrigez le JSON envoyé.
401	Clé absente, invalide, révoquée ou expirée	Vérifiez la clé. Ne réessayez pas à l’identique.
403	Permission manquante, adresse IP refusée	Ajoutez la permission à la clé, ou autorisez l’adresse.
404	Ressource introuvable dans cette boutique	Vérifiez l’identifiant.
409	Conflit d’état	L’action n’est pas possible dans l’état actuel (voir ci-dessous).
413	Corps trop volumineux (plus de 256 Ko)	Réduisez le contenu.
422	Données invalides	Lisez `errors`, corrigez, renvoyez.
429	Limite de débit	Attendez `Retry-After`.
500	Erreur côté Pulse-Sell	Réessayez avec une attente croissante ; conservez `X-Request-Id`.

Codes d’erreur

Code	Statut	Détail
`missing_api_key`	401	Pas d’en-tête `Authorization`.
`invalid_api_key`	401	Clé inconnue ou secret incorrect.
`api_key_revoked`	401	Clé révoquée.
`api_key_expired`	401	Clé expirée.
`ip_not_allowed`	403	Adresse non autorisée pour cette clé.
`missing_scope`	403	`errors.scopes` liste la permission manquante.
`store_unavailable`	403	La boutique de la clé n’existe plus.
`not_found`	404	Ressource inexistante ou appartenant à une autre boutique.
`validation_failed`	422	`errors` détaille chaque champ fautif.
`invalid_discount_code`	422	Code promo inconnu, inactif, expiré ou épuisé.
`invalid_state`	409	Ex. annuler une commande déjà payée.
`conflict`	409	Doublon ou état incompatible.
`idempotency_key_reuse`	422	Même `Idempotency-Key` pour une requête différente.
`idempotency_in_progress`	409	Requête identique encore en cours.
`rate_limited`	429	Trop de requêtes.
`server_error`	500	Erreur interne.

Traiter les erreurs proprement

const res = await fetch(url, options);
if (res.ok) return (await res.json()).data;

const err = await res.json();
switch (err.code) {
  case "validation_failed":
    // err.errors = { champ: [messages] } : à afficher à l'utilisateur
    throw new FormError(err.errors);
  case "rate_limited":
    // attendez res.headers.get("retry-after") puis réessayez
    break;
  case "missing_scope":
    // erreur de configuration : ajoutez err.errors.scopes à la clé
    throw new Error(`Permission manquante : ${err.errors.scopes}`);
  default:
    console.error("Pulse-Sell", res.headers.get("x-request-id"), err);
}

res = requests.get(url, headers=headers)
if res.ok:
    return res.json()["data"]

err = res.json()
if err["code"] == "validation_failed":
    raise FormError(err["errors"])
if err["code"] == "missing_scope":
    raise RuntimeError(f"Permission manquante : {err['errors']['scopes']}")
log.error("Pulse-Sell %s %s", res.headers.get("X-Request-Id"), err)

Pour des raisons de sécurité, une ressource qui existe dans une autre boutique répond comme une ressource inexistante (404). Rien ne permet de deviner ce qui existe ailleurs.