Codes d'erreur

Codes de statut HTTP

Code	Signification	Action recommandée
200	Requête acceptée (le traitement des écritures est asynchrone)	Continuer
400	Requête invalide (JSON malformé, paramètre incorrect)	Corriger la requête
401	Clé API manquante ou invalide (spm-api-key)	Vérifier la clé
403	Accès refusé pour cette ressource	Vérifier les droits de la clé
404	Ressource introuvable	Vérifier l'identifiant
409	Conflit (ex. contrainte d'unicité)	Adapter la donnée
422	Échec de validation du payload	Corriger les champs signalés
429	Trop de requêtes (rate limit)	Ré-essayer après backoff
500 502 503 504	Erreur ou indisponibilité serveur	Ré-essayer avec backoff

Suppressions idempotentes

Les opérations delete* et bulkDelete* sont idempotentes : supprimer un identifiant inconnu réussit silencieusement (pas de 404).

Écritures en lot : rejets partiels

Une écriture en lot (POST / PUT / bulk-delete) renvoie 200 même si certains items sont rejetés. Les items invalides n'interrompent pas le batch :

{
  "statusCode": 200,
  "sent_count": 18,
  "rejected_count": 2,
  "rejected_items": [
    { "index": 4, "errors": ["email must be a valid email"] }
  ]
}

Vérifiez toujours rejected_count / rejected_items — un 200 confirme l'acceptation, pas que tous les items ont été acceptés.

Gestion des erreurs avec le SDK

Le SDK JavaScript ne lève jamais d'exception sur une erreur HTTP : il renvoie une enveloppe uniforme dont le champ error porte un code normalisé.

const res = await SpmOrders.bulkSave(client, orders);

if (!res.ok) {
  console.log(res.error.code);       // 'HTTP_429', 'HTTP_503', 'ETIMEDOUT', …
  console.log(res.error.retryable);  // true si l'erreur est transitoire
  console.log(res.error.attempts);   // nombre de tentatives effectuées
}

Type	error.code	retryable
HTTP 4xx (hors 408/429)	HTTP_4xx	false
HTTP 408 / 429	HTTP_408 / HTTP_429	true
HTTP 5xx	HTTP_5xx	true
Réseau	ETIMEDOUT, ECONNRESET, ECONNREFUSED, ENOTFOUND, …	true

Le SDK retry automatiquement les erreurs retryable (408 / 429 / 5xx / réseau) avec un backoff exponentiel — voir Résilience. SpmHelpers.formatError(res) produit un objet sûr à journaliser.

Sans le SDK

En appel direct (fetch / cURL / PHP), testez le code de statut HTTP et la présence de rejected_items dans le corps. Implémentez votre propre backoff sur 429 et 5xx.